diff --git a/VERSION b/VERSION
index 3df5a469..07a21997 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.0.29
+2.0.30
diff --git a/backend/app/api/browser.py b/backend/app/api/browser.py
index e67bdd92..a8325848 100644
--- a/backend/app/api/browser.py
+++ b/backend/app/api/browser.py
@@ -45,6 +45,7 @@
     ContentTransferResult,
     CopyMoveRequest,
     CreateItemRequest,
+    DirectoryIssueDetail,
     DirectoryListing,
     DirectorySearchResult,
     FileInfo,
@@ -1075,6 +1076,7 @@ async def search_directories(
     connection_id: uuid.UUID,
     q: str = Query("", max_length=MAX_QUERY_BYTES, description="Directory search text; shared UTF-8 byte and term limits apply"),
     include_dot_directories: bool = Query(False, description="Whether to include directories whose path contains dot-prefixed segments"),
+    include_issue_details: bool = Query(False, description="Include bounded directory issue details for the status dialog"),
     current_user: User = Depends(get_current_user_with_auth_check),
     session: Session = Depends(get_session),
 ) -> DirectorySearchResult:
@@ -1122,6 +1124,9 @@ async def search_directories(
             except asyncio.CancelledError:
                 cancelled.set()
                 raise
+            details, incomplete = (
+                cache.directory_issue_details() if response.issue_count and response.coverage == "partial" else ([], False)
+            )
             return DirectorySearchResult(
                 results=[row.path for row in response.results],
                 match_ranks={row.path: row.match_rank for row in response.results},
@@ -1133,6 +1138,9 @@ async def search_directories(
                 accepted_revision=response.accepted_revision,
                 coverage=response.coverage,
                 coverage_issue_count=response.issue_count,
+                issue_details_available=bool(details),
+                issue_details=[DirectoryIssueDetail.model_validate(detail) for detail in details] if include_issue_details else None,
+                issue_details_incomplete=incomplete,
                 last_verified_at_ms=response.last_verified_at_ms,
                 status_message=cache.scan_error,
                 monitoring_state=cache.monitoring_state,
diff --git a/backend/app/models/file.py b/backend/app/models/file.py
index da043d2c..33c180f5 100644
--- a/backend/app/models/file.py
+++ b/backend/app/models/file.py
@@ -144,6 +144,13 @@ def validate_factual_outcome(self) -> "ContentTransferResult":
         return self
 
 
+class DirectoryIssueDetail(BaseModel):
+    """A directory that could not be fully read during verification."""
+
+    path: str
+    code: Literal["access_denied", "unsupported_encoding", "unsafe_traversal", "scan_failed"]
+
+
 class DirectorySearchResult(BaseModel):
     """Response model for directory search (quick navigate)."""
 
@@ -157,6 +164,9 @@ class DirectorySearchResult(BaseModel):
     accepted_revision: int | None = Field(default=None, ge=0)
     coverage: str | None = None
     coverage_issue_count: int = Field(default=0, ge=0)
+    issue_details_available: bool = False
+    issue_details: list[DirectoryIssueDetail] | None = None
+    issue_details_incomplete: bool = False
     last_verified_at_ms: int | None = Field(default=None, ge=0)
     status_message: str | None = None
     monitoring_state: Literal["starting", "healthy", "recovering", "unavailable"] | None = None
diff --git a/backend/app/services/directory_cache.py b/backend/app/services/directory_cache.py
index 4e8be6bf..19aeb926 100644
--- a/backend/app/services/directory_cache.py
+++ b/backend/app/services/directory_cache.py
@@ -86,6 +86,7 @@ class CacheState(str, Enum):
     """State of a connection's directory cache."""
 
     EMPTY = "empty"  # No scan started yet
+    OPENING = "opening"
     BUILDING = "building"  # Initial scan in progress
     READY = "ready"  # Scan complete, cache is usable
     UPDATING = "updating"  # Rescan in progress, stale data served
@@ -254,9 +255,26 @@ def __init__(
         self._streamed_parent_reads: set[int] = set()
         self._completed_scan_reads: set[int] = set()
         self._pending_scan_issues: dict[int, dict[str, int]] = {}
+        self.issue_details: set[tuple[str, str]] = set()
+        self.issue_details_incomplete = False
         self.scan_commits = 0
         self.on_scan_commit: Callable[[int], None] | None = None
 
+    def _publish_issue_details(self, parent: str, counts: dict[str, int]) -> None:
+        """Publish diagnostics only after the owning parent transaction succeeds."""
+        self.issue_details = {detail for detail in self.issue_details if detail[0] != parent}
+        for code in counts:
+            if len(self.issue_details) < MAX_LOGGED_SCAN_ISSUES_PER_PASS:
+                self.issue_details.add((parent, code))
+            else:
+                self.issue_details_incomplete = True
+
+    def _discard_missing_issue_details(self, generation_id: int) -> None:
+        """Remove samples for subtrees pruned by committed parent snapshots."""
+        self.issue_details = {
+            detail for detail in self.issue_details if not detail[0] or self.index.contains_directory(generation_id, detail[0])
+        }
+
     def start_scan_groups(self, *, reconcile: bool = False) -> None:
         with self.lock:
             self._scan_group = {}
@@ -341,6 +359,9 @@ def flush_scan_group(self) -> None:
                     if file_ids[generation]:
                         options["file_ids"] = file_ids[generation]
                     self.index.commit_scan_parents(generation, results, **options)
+                    for parent, _children in results:
+                        self._publish_issue_details(parent, issues.get(parent, {}))
+                    self._discard_missing_issue_details(generation)
                     self.scan_commits += 1
                 if self.on_scan_commit is not None:
                     for generation in changed:
@@ -579,6 +600,10 @@ def apply_pending(self) -> int:
                     self.index.mutate_observed_path("add", mutation.path)
                 elif mutation.action == FileAction.FILE_ACTION_REMOVED:
                     self.index.mutate_observed_path("remove", mutation.path)
+                    prefix = mutation.path + "/"
+                    self.issue_details = {
+                        detail for detail in self.issue_details if detail[0] != mutation.path and not detail[0].startswith(prefix)
+                    }
                 elif mutation.action == FileAction.FILE_ACTION_RENAMED_NEW_NAME:
                     self.index.mutate_observed_path("rename", mutation.path, mutation.new_path)
                 else:
@@ -656,6 +681,9 @@ def record_issue(self, token: ScanReadToken, generation_id: int, code: str, *, r
                     self.flush_scan_group_if_due()
             else:
                 self.index.record_issue(generation_id, code, reconcile=reconcile)
+                counts = {previous_code: 1 for parent, previous_code in self.issue_details if parent == token.path}
+                counts[code] = 1
+                self._publish_issue_details(token.path, counts)
 
     def _record_scan_issue(self, token: ScanReadToken, generation_id: int, record: Callable[[int], None]) -> None:
         with self.lock:
@@ -689,6 +717,8 @@ def finish_parent(self, token: ScanReadToken, generation_id: int, *, reconcile:
                     if token.producer_id in self._pending_scan_issues
                     else None,
                 )
+                self._publish_issue_details(token.path, self._pending_scan_issues.get(token.producer_id, {}))
+                self._discard_missing_issue_details(generation_id)
             elif self._scan_group is not None:
                 existing = self._scan_group.get(token.producer_id)
                 snapshot_children = existing.children if existing is not None else []
@@ -1543,7 +1573,7 @@ async def start_scan(self) -> None:
         if self._scan_task is not None and not self._scan_task.done():
             return
         self._owning_loop = asyncio.get_running_loop()
-        self._state = CacheState.BUILDING
+        self._state = CacheState.OPENING
         self._scan_task = asyncio.create_task(self._initialize())
 
     async def _initialize(self) -> None:
@@ -1706,6 +1736,12 @@ def _classify_source_error(error: Exception) -> str | None:
             return "unsupported_encoding"
         return "scan_failed"
 
+    def directory_issue_details(self) -> tuple[list[dict[str, str]], bool]:
+        """Return bounded, source-local diagnostics, never a persistent error history."""
+        with self.coordinator.lock:
+            details = [{"path": parent or "/", "code": code} for parent, code in sorted(self.coordinator.issue_details)]
+            return details, self.coordinator.issue_details_incomplete
+
     def _record_item_issue(self, token: ScanReadToken, generation: int, code: str, *, reconcile: bool, path: str | None = None) -> None:
         self.coordinator.record_issue(token, generation, code, reconcile=reconcile)
         self._scan_issue_counts[code] = self._scan_issue_counts.get(code, 0) + 1
@@ -2293,6 +2329,8 @@ def _scan_disk_queue(self) -> None:
                     resuming = self.index.has_resumable_scan()
                     generation, _selected = self.index.prepare_scan()
                     if not resuming:
+                        self.coordinator.issue_details.clear()
+                        self.coordinator.issue_details_incomplete = False
                         self._scan_epoch = (generation, baseline)
                     if self.coordinator.observation_lost:
                         while self.index.requeue_completed_scan_batch(generation):
diff --git a/backend/app/services/directory_index.py b/backend/app/services/directory_index.py
index 93398e91..f38d7eb6 100644
--- a/backend/app/services/directory_index.py
+++ b/backend/app/services/directory_index.py
@@ -954,6 +954,17 @@ def scan_parent_file_id(self, generation_id: int, parent: str) -> bytes | None:
             )
             return None if row is None or row[0] is None else bytes(row[0])
 
+    def contains_directory(self, generation_id: int, path: str) -> bool:
+        """Check whether a sampled directory remains in the committed generation."""
+        validate_directory_path(path)
+        with self._writer_lock:
+            return (
+                self._connection()
+                .execute("SELECT 1 FROM directories WHERE generation_id = ? AND path = ?", (generation_id, path))
+                .fetchone()
+                is not None
+            )
+
     def write_scan_children(
         self, generation_id: int, children: Iterable[tuple[str, bool]], *, file_ids: dict[str, bytes] | None = None
     ) -> None:
diff --git a/backend/tests/test_directory_cache.py b/backend/tests/test_directory_cache.py
index 126a1dd1..906805bc 100644
--- a/backend/tests/test_directory_cache.py
+++ b/backend/tests/test_directory_cache.py
@@ -350,6 +350,7 @@ def test_enum_values(self):
         """Verify all expected cache states exist with correct values."""
 
         assert CacheState.EMPTY.value == "empty"
+        assert CacheState.OPENING.value == "opening"
         assert CacheState.BUILDING.value == "building"
         assert CacheState.READY.value == "ready"
         assert CacheState.UPDATING.value == "updating"
@@ -363,7 +364,14 @@ def test_enum_is_string(self):
     def test_enum_member_count(self):
         """Ensure no unexpected states were added."""
 
-        assert len(CacheState) == 4
+        expected_states = (
+            CacheState.EMPTY,
+            CacheState.OPENING,
+            CacheState.BUILDING,
+            CacheState.READY,
+            CacheState.UPDATING,
+        )
+        assert len(CacheState) == len(expected_states)
 
 
 # ============================================================================
diff --git a/backend/tests/test_directory_index_contract.py b/backend/tests/test_directory_index_contract.py
index c244fbf3..121ee9ee 100644
--- a/backend/tests/test_directory_index_contract.py
+++ b/backend/tests/test_directory_index_contract.py
@@ -2205,6 +2205,31 @@ def unavailable():
     assert "Wait for active workers" in sqlite_cache.scan_error
     assert started == [True]
     assert not sqlite_cache._opened.is_set()
+    assert sqlite_cache.state.value == "empty"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("next_state", ["building", "updating", "ready"])
+async def test_cold_scan_reports_opening_until_initialization_finishes(sqlite_cache, monkeypatch, next_state):
+    from app.services.directory_cache import CacheState
+
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    async def initialize():
+        entered.set()
+        await release.wait()
+        sqlite_cache._state = CacheState(next_state)
+
+    monkeypatch.setattr(sqlite_cache, "_initialize", initialize)
+    await sqlite_cache.start_scan()
+    try:
+        await entered.wait()
+        assert sqlite_cache.state is CacheState.OPENING
+    finally:
+        release.set()
+        await sqlite_cache._scan_task
+    assert sqlite_cache.state.value == next_state
 
 
 @pytest.mark.asyncio
@@ -5253,6 +5278,32 @@ async def get_source(**kwargs):
     assert response.json()["coverage"] == "partial"
 
 
+@pytest.mark.parametrize("include_details", [False, True])
+def test_directory_api_returns_issue_details_only_on_request(
+    sqlite_cache, monkeypatch, client, auth_headers_user, test_connection, include_details
+):
+    async def get_source(**kwargs):
+        return sqlite_cache
+
+    sqlite_cache.index.seed_scan(1)
+    sqlite_cache.coordinator.start_scan_groups()
+    token = sqlite_cache.coordinator.begin_read("")
+    sqlite_cache.coordinator.record_issue(token, 1, "unsupported_encoding")
+    sqlite_cache.coordinator.finish_parent(token, 1)
+    sqlite_cache.coordinator.flush_scan_group()
+    assert sqlite_cache.index.finish_generation(1)
+    monkeypatch.setattr("app.services.directory_cache.get_directory_cache_manager", lambda: SimpleNamespace(get_or_create_cache=get_source))
+    response = client.get(
+        f"/api/browse/{test_connection.id}/directories",
+        headers=auth_headers_user,
+        params={"q": "", "include_issue_details": str(include_details).lower()},
+    )
+    assert response.status_code == 200
+    assert response.json()["issue_details_available"] is True
+    assert response.json()["issue_details"] == ([{"path": "/", "code": "unsupported_encoding"}] if include_details else None)
+    assert response.json()["issue_details_incomplete"] is False
+
+
 def test_directory_api_rejects_excess_terms_before_source_creation(monkeypatch, client, auth_headers_user, test_connection):
     def unexpected_manager():
         raise AssertionError("Invalid queries must not initialize a directory source.")
@@ -5452,6 +5503,14 @@ def scan(path, **kwargs):
     assert sqlite_cache.index.pending_scan_paths(1) == []
     assert sqlite_cache._smb_base_path + "\\readable\\child" in reads
     assert sqlite_cache.index._connection().execute("SELECT code, count FROM coverage_issues").fetchall() == [("access_denied", 1)]
+    assert sqlite_cache.directory_issue_details() == ([{"path": "denied", "code": "access_denied"}], False)
+
+    def empty_scan(*_args, **_kwargs):
+        yield from ()
+
+    monkeypatch.setattr("smbclient.scandir", empty_scan)
+    sqlite_cache._scan_disk_queue()
+    assert sqlite_cache.directory_issue_details() == ([], False)
 
 
 @pytest.mark.parametrize("failure", ["separator", "surrogate", "oversized", "folder_io", "denied"])
@@ -7376,12 +7435,14 @@ def test_scan_group_buffers_parent_issues(index, early_flush, reconcile):
         coordinator.flush_scan_group()
     coordinator.record_issue(token, 1, "unsupported_encoding", reconcile=reconcile)
     assert index.status().issue_count == 0
+    assert not coordinator.issue_details
     coordinator.finish_parent(token, 1, reconcile=reconcile)
     coordinator.flush_scan_group()
     assert index.status().issue_count == 2
     assert coordinator.scan_commits == 1
     assert not coordinator._pending_scan_issues
     assert not coordinator._producers
+    assert coordinator.issue_details == {("", "unsupported_encoding")}
 
 
 @pytest.mark.parametrize("reconcile", [False, True])
@@ -7405,6 +7466,86 @@ def test_stale_scan_group_discards_parent_issues(index, reconcile):
     assert index.scan_parent_pending(1, "")
     assert index._connection().execute("SELECT count(*) FROM coverage_issues WHERE code = 'unsupported_encoding'").fetchone() == (0,)
     assert not coordinator._pending_scan_issues
+    assert not coordinator.issue_details
+
+
+@pytest.mark.parametrize("parent_hint", [False, True])
+def test_issue_details_remove_deleted_subtree_after_reconciliation(index, parent_hint):
+    from smbprotocol.change_notify import FileAction
+
+    from app.services.directory_cache import READ_PARENT_ACTION, DirectoryScanCoordinator, _DirectoryMutation
+
+    index.seed_scan(1)
+    coordinator = DirectoryScanCoordinator(index)
+    coordinator.start_scan_groups()
+    for parent, children in [
+        ("", [("private", True), ("private-backup", True)]),
+        ("private", [("private/child", True)]),
+        ("private/child", []),
+        ("private-backup", []),
+    ]:
+        with coordinator.read(parent) as token:
+            coordinator.commit_children(token, 1, children)
+            coordinator.record_issue(token, 1, "access_denied")
+            coordinator.finish_parent(token, 1)
+        coordinator.flush_scan_group()
+    coordinator.cancel_scan_groups()
+    assert index.finish_generation(1)
+
+    mutation = _DirectoryMutation(READ_PARENT_ACTION, "") if parent_hint else _DirectoryMutation(FileAction.FILE_ACTION_REMOVED, "private")
+    assert coordinator.enqueue(mutation)
+    coordinator.apply_pending()
+    coordinator.start_scan_groups(reconcile=True)
+    with coordinator.read("") as token:
+        coordinator.commit_children(token, 1, [("private-backup", True)], reconcile=True)
+        coordinator.record_issue(token, 1, "access_denied", reconcile=True)
+        coordinator.finish_parent(token, 1, reconcile=True)
+    coordinator.flush_scan_group()
+    coordinator.cancel_scan_groups()
+
+    assert not index.search("private/child").results
+    assert coordinator.issue_details == {("", "access_denied"), ("private-backup", "access_denied")}
+
+
+def test_issue_details_preserved_when_subtree_deletion_rolls_back(index):
+    from smbprotocol.change_notify import FileAction
+
+    from app.services.directory_cache import DirectoryScanCoordinator, _DirectoryMutation
+
+    index.write_paths(["private", "private/child"])
+    assert index.finish_generation(1)
+    coordinator = DirectoryScanCoordinator(index)
+    coordinator._publish_issue_details("private", {"access_denied": 1})
+    coordinator._publish_issue_details("private/child", {"access_denied": 1})
+    samples = coordinator.issue_details.copy()
+    index._connection().execute(
+        "CREATE TRIGGER reject_sample_deletion BEFORE DELETE ON directories "
+        "WHEN OLD.path = 'private' BEGIN SELECT RAISE(ABORT, 'injected deletion failure'); END"
+    )
+    assert coordinator.enqueue(_DirectoryMutation(FileAction.FILE_ACTION_REMOVED, "private"))
+    with pytest.raises(sqlite3.IntegrityError, match="injected deletion failure"):
+        coordinator.apply_pending()
+    assert coordinator.issue_details == samples
+    assert index.contains_directory(1, "private/child")
+    assert coordinator.pending
+    index._connection().execute("DROP TRIGGER reject_sample_deletion")
+    coordinator.apply_pending()
+    assert not coordinator.issue_details
+
+
+def test_issue_detail_samples_are_bounded_and_replaced_by_clean_reads(index):
+    from app.services.directory_cache import MAX_LOGGED_SCAN_ISSUES_PER_PASS, DirectoryScanCoordinator
+
+    coordinator = DirectoryScanCoordinator(index)
+    for number in range(MAX_LOGGED_SCAN_ISSUES_PER_PASS + 1):
+        coordinator._publish_issue_details(f"parent-{number}", {"access_denied": 1})
+    assert len(coordinator.issue_details) == MAX_LOGGED_SCAN_ISSUES_PER_PASS
+    assert coordinator.issue_details_incomplete
+    coordinator._publish_issue_details("parent-0", {})
+    assert not any(parent == "parent-0" for parent, _code in coordinator.issue_details)
+    coordinator._publish_issue_details("parent-1", {"scan_failed": 1})
+    assert ("parent-1", "scan_failed") in coordinator.issue_details
+    assert ("parent-1", "access_denied") not in coordinator.issue_details
 
 
 def test_reconciliation_groups_independent_pages(smb_source_cache, smb_directory_server, monkeypatch):
diff --git a/backend/tests/test_directory_search.py b/backend/tests/test_directory_search.py
index fa62b0ea..1289439e 100644
--- a/backend/tests/test_directory_search.py
+++ b/backend/tests/test_directory_search.py
@@ -666,7 +666,7 @@ def test_model_serialization(self):
     def test_model_all_cache_states(self):
         """Model should accept all valid cache states."""
 
-        for state_value in ["empty", "building", "ready", "updating"]:
+        for state_value in ["empty", "opening", "building", "ready", "updating"]:
             result = DirectorySearchResult(
                 results=[],
                 total_matches=0,
diff --git a/companion/package-lock.json b/companion/package-lock.json
index 77fb2b82..3203fadf 100644
--- a/companion/package-lock.json
+++ b/companion/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "sambee-companion",
-  "version": "2.0.29",
+  "version": "2.0.30",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sambee-companion",
-      "version": "2.0.29",
+      "version": "2.0.30",
       "dependencies": {
         "@tauri-apps/api": "^2.12.4",
         "@tauri-apps/plugin-autostart": "^2.7.0",
diff --git a/companion/package.json b/companion/package.json
index 27a62492..b88b7ba4 100644
--- a/companion/package.json
+++ b/companion/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sambee-companion",
-  "version": "2.0.29",
+  "version": "2.0.30",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/companion/src-tauri/Cargo.lock b/companion/src-tauri/Cargo.lock
index 6125ac3b..b9d9f83c 100644
--- a/companion/src-tauri/Cargo.lock
+++ b/companion/src-tauri/Cargo.lock
@@ -3867,7 +3867,7 @@ checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
 
 [[package]]
 name = "sambee-companion"
-version = "2.0.29"
+version = "2.0.30"
 dependencies = [
  "axum",
  "base64 0.22.1",
diff --git a/companion/src-tauri/Cargo.toml b/companion/src-tauri/Cargo.toml
index 73665dc1..71635ceb 100644
--- a/companion/src-tauri/Cargo.toml
+++ b/companion/src-tauri/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "sambee-companion"
-version = "2.0.29"
+version = "2.0.30"
 edition = "2021"
 description = "Sambee Companion — opens files from Sambee in native desktop editors"
 authors = []
diff --git a/companion/src-tauri/src/server/directory_index.rs b/companion/src-tauri/src/server/directory_index.rs
index f5b2b09f..37839283 100644
--- a/companion/src-tauri/src/server/directory_index.rs
+++ b/companion/src-tauri/src/server/directory_index.rs
@@ -1277,6 +1277,15 @@ impl DirectoryIndex {
             .flatten())
     }
 
+    pub fn contains_directory(&self, generation_id: i64, path: &str) -> Result<bool, IndexError> {
+        validate_directory_path(path)?;
+        Ok(self.writer.query_row(
+            "SELECT EXISTS(SELECT 1 FROM directories WHERE generation_id = ? AND path = ?)",
+            params![generation_id, path],
+            |row| row.get(0),
+        )?)
+    }
+
     pub fn commit_scan_parents(&mut self, generation_id: i64, results: &[ScanParentResult]) -> Result<(), IndexError> {
         self.commit_scan_parents_with_ids(generation_id, results, &HashMap::new())
     }
diff --git a/companion/src-tauri/src/server/directory_manager.rs b/companion/src-tauri/src/server/directory_manager.rs
index c09d14d1..a5db187f 100644
--- a/companion/src-tauri/src/server/directory_manager.rs
+++ b/companion/src-tauri/src/server/directory_manager.rs
@@ -29,7 +29,7 @@ use super::directory_index::{
 use super::directory_traversal::NativeIdentity;
 use super::directory_traversal::{source_error, NativeIo, NativeParent, NativeRoot, TraversalIssue, MOUNT_BOUNDARY_CAPABILITY_ERROR};
 use super::drives::{volume_evidence, VolumeChange, VolumeEvidence};
-use super::models::{DirectorySearchResult, ScanProgress};
+use super::models::{DirectoryIssueDetail, DirectorySearchResult, ScanProgress};
 
 const CONTRACT_JSON: &str = include_str!("../../../../shared/directory-index/contract.json");
 const STALLED_READ_TIMEOUT: Duration = Duration::from_secs(30);
@@ -524,6 +524,8 @@ struct Observations {
     streamed_parent_reads: HashSet<u64>,
     scan_commits: usize,
     scan_issue_counts: HashMap<&'static str, usize>,
+    issue_details: HashSet<(String, &'static str)>,
+    issue_details_incomplete: bool,
     pending_scan_issues: HashMap<u64, HashMap<&'static str, usize>>,
 }
 
@@ -598,6 +600,30 @@ impl InvalidationReason {
 }
 
 impl Observations {
+    fn publish_issue_details(&mut self, parent: &str, counts: &HashMap<&'static str, usize>) -> Result<(), IndexError> {
+        self.issue_details.retain(|(path, _code)| path != parent);
+        let maximum = limit("max_logged_scan_issues_per_pass")?;
+        for code in counts.keys() {
+            if self.issue_details.len() < maximum {
+                self.issue_details.insert((parent.to_owned(), code));
+            } else {
+                self.issue_details_incomplete = true;
+            }
+        }
+        Ok(())
+    }
+
+    fn discard_missing_issue_details(&mut self, index: &DirectoryIndex, generation: i64) -> Result<(), IndexError> {
+        let mut missing = HashSet::new();
+        for (path, _code) in &self.issue_details {
+            if !path.is_empty() && !index.contains_directory(generation, path)? {
+                missing.insert(path.clone());
+            }
+        }
+        self.issue_details.retain(|(path, _code)| !missing.contains(path));
+        Ok(())
+    }
+
     fn scan_issue_bytes(&self, producer: u64) -> usize {
         self.pending_scan_issues.get(&producer).map_or(0, |counts| {
             counts.iter().map(|(code, count)| code.len() + count.to_string().len()).sum()
@@ -871,6 +897,8 @@ impl Drop for MutationObservation {
     }
 }
 
+const INDEX_OPENING_STATE: &str = "opening";
+
 struct SourceStatus {
     state: &'static str,
     message: Option<String>,
@@ -1047,7 +1075,7 @@ impl LocalSource {
             watcher_reconciling: AtomicBool::new(true),
             observations: Mutex::new(Observations::default()),
             status: Mutex::new(SourceStatus {
-                state: "building",
+                state: INDEX_OPENING_STATE,
                 message: None,
                 progress: now,
                 verified: now,
@@ -1462,7 +1490,15 @@ impl LocalSource {
                 break;
             };
             writer.mutate_observed_path(mutation)?;
-            observations.bytes -= *bytes;
+            let bytes = *bytes;
+            if let DirectoryMutation::Remove { path } = mutation {
+                let prefix = format!("{path}/");
+                let path = path.clone();
+                observations
+                    .issue_details
+                    .retain(|(parent, _code)| parent != &path && !parent.starts_with(&prefix));
+            }
+            observations.bytes -= bytes;
             observations.pending.pop_front();
         }
         observations.retire_barriers();
@@ -1771,6 +1807,16 @@ impl LocalSource {
                         issues: issues.get(&generation),
                     },
                 )?;
+                for (parent, _children) in &results {
+                    observations.publish_issue_details(
+                        parent,
+                        issues
+                            .get(&generation)
+                            .and_then(|parents| parents.get(parent))
+                            .unwrap_or(&HashMap::new()),
+                    )?;
+                }
+                observations.discard_missing_issue_details(writer, generation)?;
                 observations.scan_commits += 1;
             }
             let mut status = lock(&self.status)?;
@@ -2029,6 +2075,13 @@ impl LocalSource {
         } else {
             writer.finish_scan_parent(generation, parent)?;
         }
+        let counts = observations
+            .pending_scan_issues
+            .get(&read.token.producer)
+            .cloned()
+            .unwrap_or_default();
+        observations.publish_issue_details(parent, &counts)?;
+        observations.discard_missing_issue_details(writer, generation)?;
         lock(&self.status)?.index_status = Some(writer.status()?);
         Ok(())
     }
@@ -2099,6 +2152,14 @@ impl LocalSource {
             let writer = writer.as_mut().ok_or(IndexError::Invalid("Directory writer is unavailable."))?;
             writer.record_issue(generation, code)?;
             lock(&self.status)?.index_status = Some(writer.status()?);
+            let mut counts: HashMap<_, _> = observations
+                .issue_details
+                .iter()
+                .filter(|(path, _code)| path == parent)
+                .map(|(_path, code)| (*code, 1))
+                .collect();
+            counts.insert(code, 1);
+            observations.publish_issue_details(parent, &counts)?;
         }
         *observations.scan_issue_counts.entry(code).or_default() += 1;
         if observations.scan_issue_counts.values().sum::<usize>() <= limit("max_logged_scan_issues_per_pass")? {
@@ -2337,6 +2398,13 @@ impl LocalSource {
         } else {
             writer.finish_scan_parent(generation, parent)?;
         }
+        let counts = observations
+            .pending_scan_issues
+            .get(&read.token.producer)
+            .cloned()
+            .unwrap_or_default();
+        observations.publish_issue_details(parent, &counts)?;
+        observations.discard_missing_issue_details(writer, generation)?;
         lock(&self.status)?.index_status = Some(writer.status()?);
         Ok(())
     }
@@ -2945,6 +3013,8 @@ impl LocalSource {
             let resuming = index.has_resumable_scan()?;
             let (generation, selected) = index.prepare_scan()?;
             if !resuming {
+                observations.issue_details.clear();
+                observations.issue_details_incomplete = false;
                 observations.scan_epoch = Some((generation, baseline.token.epoch));
             }
             if observations.observation_lost {
@@ -2964,14 +3034,17 @@ impl LocalSource {
             observations.scan_commits = 0;
             observations.scan_issue_counts.clear();
             let (done, queued, found) = index.scan_counts(generation)?;
-            lock(&self.status)?.scan_progress = Some(ScanProgress {
+            let mut status = lock(&self.status)?;
+            status.state = if selected { "building" } else { "updating" };
+            status.scan_progress = Some(ScanProgress {
                 phase: if selected { "building" } else { "updating" },
                 parents_done: done,
                 parents_queued: queued,
                 directories_found: found,
                 started_at_ms: epoch_milliseconds()?,
             });
-            lock(&self.status)?.scan_generation = Some(generation);
+            status.scan_generation = Some(generation);
+            drop(status);
             log::info!(
                 "event=directory_scan_started operation=directory_index stage=scan source_id={} generation_id={} scan_generation={} scan_phase={} parents_done={} parents_queued={} directories_found={} native_opens={} group_commits=0 duration_ms={} abort_reason=none",
                 self.source_id,
@@ -3315,7 +3388,11 @@ impl LocalDirectoryManager {
         };
         {
             let mut status = lock(&source.status)?;
-            status.state = if lock(&source.reader)?.is_some() { "updating" } else { "building" };
+            status.state = if lock(&source.reader)?.is_some() {
+                "updating"
+            } else {
+                INDEX_OPENING_STATE
+            };
             status.stalled = false;
         }
         source.progress()?;
@@ -3485,6 +3562,23 @@ impl LocalDirectoryManager {
         Ok(())
     }
 
+    pub fn issue_details(&self, drive: &str) -> Result<(Vec<DirectoryIssueDetail>, bool), IndexError> {
+        let sources = lock(&self.sources)?;
+        let source = sources.get(drive).ok_or(IndexError::Interrupted)?;
+        source.ensure_available()?;
+        let observations = lock(&source.observations)?;
+        let mut details: Vec<_> = observations
+            .issue_details
+            .iter()
+            .map(|(parent, code)| DirectoryIssueDetail {
+                path: if parent.is_empty() { "/".to_owned() } else { parent.clone() },
+                code,
+            })
+            .collect();
+        details.sort_by(|left, right| (&left.path, left.code).cmp(&(&right.path, right.code)));
+        Ok((details, observations.issue_details_incomplete))
+    }
+
     pub async fn search(
         self: &Arc<Self>,
         drive: String,
@@ -3565,6 +3659,9 @@ impl LocalDirectoryManager {
                 accepted_revision: Some(0),
                 coverage: Some("partial".into()),
                 coverage_issue_count: 0,
+                issue_details_available: false,
+                issue_details: None,
+                issue_details_incomplete: false,
                 last_verified_at_ms: None,
                 status_message: status.message.clone(),
                 monitoring_state: Some(
@@ -3622,6 +3719,10 @@ impl LocalDirectoryManager {
             result?
         };
         source.ensure_available()?;
+        let observations = lock(&source.observations)?;
+        let has_details = result.coverage == "partial" && result.issue_count > 0 && !observations.issue_details.is_empty();
+        let details_incomplete = observations.issue_details_incomplete;
+        drop(observations);
         let status = lock(&source.status)?;
         let wire_count = |value: i64| -> Result<usize, IndexError> {
             if !(0..=MAX_WIRE_INTEGER).contains(&value) {
@@ -3648,6 +3749,9 @@ impl LocalDirectoryManager {
             accepted_revision: Some(result.accepted_revision),
             coverage: Some(result.coverage),
             coverage_issue_count: wire_count(result.issue_count)?,
+            issue_details_available: has_details,
+            issue_details: None,
+            issue_details_incomplete: details_incomplete,
             last_verified_at_ms: result.last_verified_at_ms,
             status_message: status.message.clone(),
             monitoring_state: Some(
@@ -3685,6 +3789,110 @@ impl Drop for LocalDirectoryManager {
 
 #[cfg(test)]
 mod tests {
+    #[test]
+    fn issue_details_remove_deleted_subtree_after_reconciliation() {
+        for parent_hint in [false, true] {
+            issue_details_remove_deleted_subtree(parent_hint);
+        }
+    }
+
+    fn issue_details_remove_deleted_subtree(parent_hint: bool) {
+        let temporary = tempfile::tempdir().unwrap();
+        let path = temporary.path().join("root");
+        std::fs::create_dir_all(path.join("private/child")).unwrap();
+        std::fs::create_dir(path.join("private-backup")).unwrap();
+        let manager = LocalDirectoryManager::new(temporary.path().join("storage")).unwrap();
+        let source = LocalSource::new(path.clone(), manager.storage_directory());
+        source.scan(&manager.budget).unwrap();
+        {
+            let mut observations = lock(&source.observations).unwrap();
+            for parent in ["", "private", "private/child", "private-backup"] {
+                observations
+                    .publish_issue_details(parent, &HashMap::from([("access_denied", 1)]))
+                    .unwrap();
+            }
+            observations
+                .enqueue(
+                    if parent_hint {
+                        DirectoryMutation::ReadParent { path: String::new() }
+                    } else {
+                        DirectoryMutation::Remove { path: "private".into() }
+                    },
+                    limit("max_pending_observations").unwrap(),
+                    limit("max_observation_bytes").unwrap(),
+                )
+                .unwrap();
+        }
+        std::fs::remove_dir_all(path.join("private")).unwrap();
+        source.flush(&manager.budget).unwrap();
+        source.reconcile(&manager.budget, &manager.scans).unwrap();
+        assert_eq!(
+            lock(&source.observations).unwrap().issue_details,
+            HashSet::from([("private-backup".to_owned(), "access_denied")])
+        );
+    }
+
+    #[test]
+    fn issue_details_preserved_when_subtree_deletion_rolls_back() {
+        let temporary = tempfile::tempdir().unwrap();
+        let path = temporary.path().join("root");
+        std::fs::create_dir_all(path.join("private/child")).unwrap();
+        let manager = LocalDirectoryManager::new(temporary.path().join("storage")).unwrap();
+        let source = LocalSource::new(path, manager.storage_directory());
+        source.scan(&manager.budget).unwrap();
+        let samples = HashSet::from([
+            ("private".to_owned(), "access_denied"),
+            ("private/child".to_owned(), "access_denied"),
+        ]);
+        {
+            let mut observations = lock(&source.observations).unwrap();
+            observations.issue_details = samples.clone();
+            observations
+                .enqueue(
+                    DirectoryMutation::Remove { path: "private".into() },
+                    limit("max_pending_observations").unwrap(),
+                    limit("max_observation_bytes").unwrap(),
+                )
+                .unwrap();
+        }
+        let connection = open_directory_database(&source.index_path, OpenFlags::SQLITE_OPEN_READ_WRITE).unwrap();
+        connection.execute_batch(
+            "CREATE TRIGGER reject_sample_deletion BEFORE DELETE ON directories WHEN OLD.path = 'private' BEGIN SELECT RAISE(ABORT, 'injected deletion failure'); END",
+        ).unwrap();
+        assert!(matches!(source.flush(&manager.budget), Err(IndexError::Sql(_))));
+        assert_eq!(lock(&source.observations).unwrap().issue_details, samples);
+        assert!(!lock(&source.observations).unwrap().pending.is_empty());
+        assert!(lock(&source.writer)
+            .unwrap()
+            .as_ref()
+            .unwrap()
+            .contains_directory(1, "private/child")
+            .unwrap());
+        connection.execute_batch("DROP TRIGGER reject_sample_deletion").unwrap();
+        source.flush(&manager.budget).unwrap();
+        assert!(lock(&source.observations).unwrap().issue_details.is_empty());
+    }
+
+    #[test]
+    fn issue_detail_samples_are_bounded_and_replaced_by_clean_reads() {
+        let mut observations = Observations::default();
+        let maximum = limit("max_logged_scan_issues_per_pass").unwrap();
+        for number in 0..=maximum {
+            observations
+                .publish_issue_details(&format!("parent-{number}"), &HashMap::from([("access_denied", 1)]))
+                .unwrap();
+        }
+        assert_eq!(observations.issue_details.len(), maximum);
+        assert!(observations.issue_details_incomplete);
+        observations.publish_issue_details("parent-0", &HashMap::new()).unwrap();
+        assert!(!observations.issue_details.iter().any(|(parent, _code)| parent == "parent-0"));
+        observations
+            .publish_issue_details("parent-1", &HashMap::from([("scan_failed", 1)]))
+            .unwrap();
+        assert!(observations.issue_details.contains(&("parent-1".to_owned(), "scan_failed")));
+        assert!(!observations.issue_details.contains(&("parent-1".to_owned(), "access_denied")));
+    }
+
     #[test]
     fn scan_group_buffers_parent_issues() {
         for (early_flush, stale, reconcile) in [
@@ -3728,6 +3936,7 @@ mod tests {
                 .record_item_issue(1, "", read.token, "unsupported_encoding", &manager.budget)
                 .unwrap();
             assert_eq!(lock(&source.writer).unwrap().as_ref().unwrap().status().unwrap().issue_count, 0);
+            assert!(lock(&source.observations).unwrap().issue_details.is_empty());
             let mut observations = lock(&source.observations).unwrap();
             source
                 .complete_scan_parent_locked(&mut observations, ScanGeneration { id: 1, read: read.token }, "", &manager.budget)
@@ -3744,6 +3953,7 @@ mod tests {
             assert_eq!(observations.scan_commits, usize::from(!stale));
             assert!(observations.pending_scan_issues.is_empty());
             assert!(observations.producers.is_empty());
+            assert_eq!(observations.issue_details.len(), usize::from(!stale));
             assert_eq!(
                 lock(&source.writer).unwrap().as_ref().unwrap().status().unwrap().issue_count,
                 if stale { 0 } else { 2 }
@@ -4289,6 +4499,25 @@ mod tests {
         }
     }
 
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn cold_source_reports_opening_before_scan_progress() {
+        let temporary = tempfile::tempdir().unwrap();
+        let path = temporary.path().join("root");
+        std::fs::create_dir(&path).unwrap();
+        let manager = LocalDirectoryManager::new(temporary.path().join("private")).unwrap();
+        let source = LocalSource::new(path, manager.storage_directory());
+        {
+            let status = lock(&source.status).unwrap();
+            assert_eq!(status.state, INDEX_OPENING_STATE);
+            assert!(status.scan_progress.is_none());
+        }
+        source.scan(&manager.budget).unwrap();
+        let status = lock(&source.status).unwrap();
+        assert_eq!(status.state, "ready");
+        assert_eq!(status.scan_progress.as_ref().unwrap().phase, "idle");
+    }
+
     #[cfg(target_os = "linux")]
     #[test]
     fn full_pass_root_probes_have_a_fixed_open_budget() {
diff --git a/companion/src-tauri/src/server/handlers.rs b/companion/src-tauri/src/server/handlers.rs
index 34a7cc72..5f7d8859 100644
--- a/companion/src-tauri/src/server/handlers.rs
+++ b/companion/src-tauri/src/server/handlers.rs
@@ -5652,6 +5652,7 @@ pub struct DirectorySearchQuery {
     pub q: Option<String>,
     /// Whether to include directories with dot-prefixed path segments.
     pub include_dot_directories: Option<bool>,
+    pub include_issue_details: Option<bool>,
 }
 
 /// `GET /api/browse/{drive}/directories` — search for directories on a local drive.
@@ -5667,11 +5668,11 @@ pub async fn browse_search_directories(
     let q = query.q.unwrap_or_default();
     let include_dot_directories = query.include_dot_directories.unwrap_or(false);
     super::directory_index::search_terms(&q).map_err(|error| ApiError::BadRequest(error.to_string()))?;
-    state
+    let details_drive = drive.clone();
+    let mut response = state
         .0
         .search(drive, base_path, q, include_dot_directories)
         .await
-        .map(Json)
         .map_err(|error| match error {
             super::directory_index::IndexError::QueryBusy => ApiError::TooManyRequests(error.to_string()),
             super::directory_index::IndexError::Invalid(message) => ApiError::BadRequest(message.to_owned()),
@@ -5679,7 +5680,20 @@ pub async fn browse_search_directories(
                 ApiError::TooManyRequests("Directory query was cancelled or timed out. Retry the search.".to_owned())
             }
             _ => ApiError::Internal("Directory search failed. Check drive access and private local storage, then retry.".to_owned()),
-        })
+        })?;
+    if query.include_issue_details.unwrap_or(false) {
+        let (details, incomplete) = if response.issue_details_available {
+            state
+                .0
+                .issue_details(&details_drive)
+                .map_err(|error| ApiError::Internal(error.to_string()))?
+        } else {
+            (Vec::new(), false)
+        };
+        response.issue_details = Some(details);
+        response.issue_details_incomplete = incomplete;
+    }
+    Ok(Json(response))
 }
 
 // ─── Upload ──────────────────────────────────────────────────────────────────
diff --git a/companion/src-tauri/src/server/models.rs b/companion/src-tauri/src/server/models.rs
index 20fcf9ec..77161ad4 100644
--- a/companion/src-tauri/src/server/models.rs
+++ b/companion/src-tauri/src/server/models.rs
@@ -638,6 +638,12 @@ pub struct ScanProgress {
     pub started_at_ms: i64,
 }
 
+#[derive(Debug, Serialize)]
+pub struct DirectoryIssueDetail {
+    pub path: String,
+    pub code: &'static str,
+}
+
 #[derive(Debug, Serialize)]
 pub struct DirectorySearchResult {
     pub results: Vec<String>,
@@ -650,6 +656,9 @@ pub struct DirectorySearchResult {
     pub accepted_revision: Option<i64>,
     pub coverage: Option<String>,
     pub coverage_issue_count: usize,
+    pub issue_details_available: bool,
+    pub issue_details: Option<Vec<DirectoryIssueDetail>>,
+    pub issue_details_incomplete: bool,
     pub last_verified_at_ms: Option<i64>,
     pub status_message: Option<String>,
     pub monitoring_state: Option<String>,
diff --git a/companion/src-tauri/tauri.conf.json b/companion/src-tauri/tauri.conf.json
index ee622e00..ef45c607 100644
--- a/companion/src-tauri/tauri.conf.json
+++ b/companion/src-tauri/tauri.conf.json
@@ -2,7 +2,7 @@
   "$schema": "https://raw.githubusercontent.com/nicegui/tauri-v2-schema/refs/heads/main/tauri.conf.json.schema",
   "productName": "Sambee Companion",
   "identifier": "app.sambee.companion",
-  "version": "2.0.29",
+  "version": "2.0.30",
   "build": {
     "beforeDevCommand": "npm run dev",
     "devUrl": "http://localhost:1420",
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 6cd30b9b..f4be94d6 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "sambee-frontend",
-  "version": "2.0.29",
+  "version": "2.0.30",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sambee-frontend",
-      "version": "2.0.29",
+      "version": "2.0.30",
       "hasInstallScript": true,
       "dependencies": {
         "@codemirror/autocomplete": "^6.20.4",
diff --git a/frontend/package.json b/frontend/package.json
index 5b6bbdeb..05a41af9 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sambee-frontend",
-  "version": "2.0.29",
+  "version": "2.0.30",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/frontend/src/components/FileBrowser/SearchStatusDialog.tsx b/frontend/src/components/FileBrowser/SearchStatusDialog.tsx
new file mode 100644
index 00000000..d95d45a1
--- /dev/null
+++ b/frontend/src/components/FileBrowser/SearchStatusDialog.tsx
@@ -0,0 +1,75 @@
+import { Box, Button, CircularProgress, Typography } from "@mui/material";
+import { useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { ResponsiveDialogShell } from "../Dialog/ResponsiveDialogShell";
+import type { SearchStatusDetails, SearchStatusInfo } from "./search/types";
+
+export function SearchStatusDialog({ status, onClose }: { status: SearchStatusInfo; onClose: () => void }) {
+  const { t } = useTranslation();
+  const [details, setDetails] = useState<SearchStatusDetails | null>(null);
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    setDetails(null);
+    setFailed(false);
+    status
+      .loadDetails?.(controller.signal)
+      .then((value) => {
+        if (!controller.signal.aborted) setDetails(value);
+      })
+      .catch(() => {
+        if (!controller.signal.aborted) setFailed(true);
+      });
+    return () => controller.abort();
+  }, [status]);
+
+  const hasDetails = !!details?.message || !!details?.issues?.length;
+  return (
+    <ResponsiveDialogShell
+      open
+      title={t("fileBrowser.search.statusDetails.title")}
+      onClose={onClose}
+      actions={
+        <Button autoFocus variant="contained" onClick={onClose}>
+          {t("common.actions.close")}
+        </Button>
+      }
+    >
+      {!details && !failed && <CircularProgress size={24} aria-label={t("app.loading")} />}
+      {failed && <Typography role="alert">{t("fileBrowser.search.statusDetails.failed")}</Typography>}
+      {details && !hasDetails && <Typography role="status">{t("fileBrowser.search.statusDetails.unavailable")}</Typography>}
+      {details && hasDetails && (
+        <>
+          <Typography variant="caption">{t("fileBrowser.search.statusDetails.source")}</Typography>
+          <Typography sx={{ overflowWrap: "anywhere", mb: 2 }}>{details.source}</Typography>
+          {details.message && <Typography sx={{ mb: 2, overflowWrap: "anywhere" }}>{details.message}</Typography>}
+          {!!details.issues?.length && (
+            <>
+              <Typography variant="body2" sx={{ mb: 2 }}>
+                {t("fileBrowser.search.statusDetails.impact")}
+              </Typography>
+              {details.incomplete && (
+                <Typography role="status" variant="body2" sx={{ mb: 2 }}>
+                  {t("fileBrowser.search.statusDetails.incomplete")}
+                </Typography>
+              )}
+              <Box component="ul" sx={{ m: 0, pl: 2 }}>
+                {details.issues.map((issue) => (
+                  <Box component="li" key={`${issue.path}:${issue.code}`} sx={{ mb: 2 }}>
+                    <Typography component="bdi" dir="auto" sx={{ display: "block", overflowWrap: "anywhere", userSelect: "text" }}>
+                      {issue.path}
+                    </Typography>
+                    <Typography variant="body2" color="text.secondary">
+                      {t(`fileBrowser.search.statusDetails.reasons.${issue.code}`)}
+                    </Typography>
+                  </Box>
+                ))}
+              </Box>
+            </>
+          )}
+        </>
+      )}
+    </ResponsiveDialogShell>
+  );
+}
diff --git a/frontend/src/components/FileBrowser/UnifiedSearchBar.tsx b/frontend/src/components/FileBrowser/UnifiedSearchBar.tsx
index 194e7b34..a83225d1 100644
--- a/frontend/src/components/FileBrowser/UnifiedSearchBar.tsx
+++ b/frontend/src/components/FileBrowser/UnifiedSearchBar.tsx
@@ -41,7 +41,7 @@ import {
 } from "@mui/material";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import type React from "react";
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useEffectEvent, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { flushSync } from "react-dom";
 import { useTranslation } from "react-i18next";
 import { usePillButtonMenu } from "../../hooks/usePillButtonMenu";
@@ -54,7 +54,8 @@ import {
   QuickBarResultGroupHeader,
   QuickBarResultRow,
 } from "./QuickBarResultRow";
-import type { SearchProvider, SearchResult, SearchSelectionAction, SearchSelectionBehavior } from "./search/types";
+import { SearchStatusDialog } from "./SearchStatusDialog";
+import type { SearchProvider, SearchResult, SearchSelectionAction, SearchSelectionBehavior, SearchStatusInfo } from "./search/types";
 
 // ============================================================================
 // Constants
@@ -196,6 +197,7 @@ export function UnifiedSearchBar({
   const [removeError, setRemoveError] = useState(false);
   const [isFocused, setIsFocused] = useState(false);
   const [isSearchPending, setIsSearchPending] = useState(false);
+  const [statusDialog, setStatusDialog] = useState<SearchStatusInfo | null>(null);
 
   const theme = useTheme();
   const { t } = useTranslation();
@@ -851,12 +853,28 @@ export function UnifiedSearchBar({
     return height;
   }, [results]);
 
+  const resetOpenResults = useEffectEvent(() => {
+    const firstIndex = Math.max(
+      results.findIndex((result) => result.kind === "result"),
+      0
+    );
+    selectedValueRef.current = results[firstIndex]?.value;
+    setSelectedIndex(firstIndex);
+    rowVirtualizer.scrollToOffset(0);
+  });
+
+  useLayoutEffect(() => {
+    if (listContainer) {
+      resetOpenResults();
+    }
+  }, [listContainer]);
+
   // ── Scroll selected item into view ─────────────────────────────────────
   useEffect(() => {
-    if (results.length > 0) {
+    if (listContainer && results.length > 0) {
       rowVirtualizer.scrollToIndex(selectedIndex, { align: "auto" });
     }
-  }, [selectedIndex, results.length, rowVirtualizer]);
+  }, [listContainer, selectedIndex, results.length, rowVirtualizer]);
 
   // ── Focus activation ───────────────────────────────────────────────────
 
@@ -876,8 +894,9 @@ export function UnifiedSearchBar({
   // handleClickAway
   //
   const handleClickAway = useCallback(() => {
+    if (statusDialog) return;
     dismissSearch();
-  }, [dismissSearch]);
+  }, [dismissSearch, statusDialog]);
 
   // ── Re-open on typing after click-away ─────────────────────────────────
   //
@@ -902,8 +921,8 @@ export function UnifiedSearchBar({
     }
 
     if (
-      (!hasSearched && query.length === 0 && effectiveMinQueryLength === 0) ||
-      (newlyActivated && hasSearched && query.length >= effectiveMinQueryLength)
+      newlyActivated &&
+      ((!hasSearched && query.length === 0 && effectiveMinQueryLength === 0) || (hasSearched && query.length >= effectiveMinQueryLength))
     ) {
       void executeSearch(query);
     }
@@ -993,7 +1012,10 @@ export function UnifiedSearchBar({
     const shouldOpenOnActivation = shouldSearchOnActivation || shouldShowBelowMinimumOnActivation;
     const shouldPreserveSearchStateOnActivation = shouldSearchOnActivation && !providerChanged;
 
-    if (!shouldPreserveSearchStateOnActivation) {
+    setStatusDialog(null);
+    if (shouldPreserveSearchStateOnActivation) {
+      resetOpenResults();
+    } else {
       setResults([]);
       setSelectedIndex(0);
       setHasSearched(false);
@@ -1012,14 +1034,14 @@ export function UnifiedSearchBar({
     lastResetProviderRef.current = provider;
     lastActivationTokenRef.current = activationToken;
 
-    activatedRef.current = isInputFocused;
+    activatedRef.current = isInputFocused || shouldSearchOnActivation;
 
-    if (shouldSearchOnActivation) {
-      void executeSearch(nextQuery);
+    if (activatedRef.current) {
+      providerRef.current.onActivate?.();
     }
 
-    if (isInputFocused) {
-      providerRef.current.onActivate?.();
+    if (shouldSearchOnActivation) {
+      void executeSearch(nextQuery);
     }
   }, [
     activationToken,
@@ -1069,14 +1091,17 @@ export function UnifiedSearchBar({
     }
   }, [disableDropdown, executeSearch, getEffectiveMinQueryLength, query, refreshToken, suppressDropdown]);
 
-  useEffect(() => {
-    if (disableDropdown || suppressDropdown) {
-      return;
+  const resumeFocusedSearch = useEffectEvent(() => {
+    if (document.activeElement === effectiveInputRef.current && query.length >= getEffectiveMinQueryLength(query)) {
+      void executeSearch(query);
     }
-    if (document.activeElement === effectiveInputRef.current && provider.minQueryLength === 0) {
-      void executeSearch("");
+  });
+
+  useEffect(() => {
+    if (!disableDropdown && !suppressDropdown && provider.minQueryLength === 0) {
+      resumeFocusedSearch();
     }
-  }, [disableDropdown, effectiveInputRef, executeSearch, provider.minQueryLength, suppressDropdown]);
+  }, [disableDropdown, provider.minQueryLength, suppressDropdown]);
 
   useEffect(() => {
     if (isModeMenuOpen && isDropdownOpen) {
@@ -1232,6 +1257,10 @@ export function UnifiedSearchBar({
             {/* Status indicator */}
             {statusInfo && (
               <Box
+                role={statusInfo.loadDetails ? "link" : undefined}
+                tabIndex={statusInfo.loadDetails ? -1 : undefined}
+                onPointerDown={statusInfo.loadDetails ? (event) => event.preventDefault() : undefined}
+                onClick={statusInfo.loadDetails ? () => setStatusDialog(statusInfo) : undefined}
                 sx={{
                   px: 2,
                   py: 0.5,
@@ -1240,10 +1269,16 @@ export function UnifiedSearchBar({
                   gap: 1,
                   borderBottom: results.length > 0 || showNoResults || showSearchError || showRemoveError ? 1 : 0,
                   borderColor: "divider",
+                  cursor: statusInfo.loadDetails ? "pointer" : undefined,
+                  textDecoration: statusInfo.loadDetails ? "underline" : undefined,
+                  "&:hover": statusInfo.loadDetails ? { color: "primary.main" } : {},
                 }}
               >
                 {statusInfo.showSpinner && <CircularProgress size={14} />}
-                <Typography variant="caption" sx={{ color: "text.secondary" }}>
+                <Typography
+                  variant="caption"
+                  sx={{ color: statusInfo.loadDetails ? "inherit" : "text.secondary", overflowWrap: "anywhere" }}
+                >
                   {statusInfo.label}
                 </Typography>
               </Box>
@@ -1408,6 +1443,7 @@ export function UnifiedSearchBar({
             )}
           </Paper>
         </Popper>
+        {statusDialog && <SearchStatusDialog status={statusDialog} onClose={() => setStatusDialog(null)} />}
       </Box>
     </ClickAwayListener>
   );
diff --git a/frontend/src/components/FileBrowser/__tests__/UnifiedSearchBar.test.tsx b/frontend/src/components/FileBrowser/__tests__/UnifiedSearchBar.test.tsx
index c3d9748b..7b8b2aee 100644
--- a/frontend/src/components/FileBrowser/__tests__/UnifiedSearchBar.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/UnifiedSearchBar.test.tsx
@@ -4,13 +4,16 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { setLocale, translate } from "../../../i18n";
 import { browserHistoryService } from "../../../services/browserHistoryService";
 import { SambeeThemeProvider } from "../../../theme/ThemeContext";
+import { type FileEntry, FileType } from "../../../types";
 import { getQuickBarResultRowHeight, QUICK_BAR_RESULT_GROUP_HEADER_HEIGHT, QUICK_BAR_RESULT_ITEM_HEIGHT } from "../QuickBarResultRow";
 import { SEARCH_CONTRACT_VERSION } from "../search/recentHistory";
 import type { SearchProvider, SearchResultsUpdate } from "../search/types";
 import { useDirectorySearchProvider } from "../search/useDirectorySearchProvider";
+import { useFileSearchProvider } from "../search/useFileSearchProvider";
 import { UnifiedSearchBar } from "../UnifiedSearchBar";
 
 const virtualizerSizeCache = new Map<string | number, number>();
+const virtualizerScrollToOffset = vi.fn();
 const INPUT_DEBOUNCE_MS = 160;
 const QUIET_REFRESH_INTERVAL_MS = 500;
 const MOCK_HISTORY_RESPONSE_MS = 40;
@@ -48,6 +51,7 @@ vi.mock("@tanstack/react-virtual", () => ({
           return virtualItem;
         });
       },
+      scrollToOffset: virtualizerScrollToOffset,
       scrollToIndex: vi.fn(),
     };
   },
@@ -634,6 +638,7 @@ describe("UnifiedSearchBar", () => {
   afterEach(async () => {
     cleanup();
     virtualizerSizeCache.clear();
+    virtualizerScrollToOffset.mockClear();
     await setLocale("en");
   });
 
@@ -694,6 +699,74 @@ describe("UnifiedSearchBar", () => {
     expect(screen.queryByText("Loading history")).not.toBeInTheDocument();
   });
 
+  it("opens status details by pointer without changing the query or list selection", async () => {
+    const user = userEvent.setup();
+    const loadDetails = vi.fn(async () => ({
+      source: "FS1",
+      issues: [{ path: "private", code: "access_denied" as const }],
+      incomplete: true,
+    }));
+    const status = { label: "FS1: not all directories could be indexed.", showSpinner: false, loadDetails };
+    renderWithProvider(<UnifiedSearchBar provider={{ ...footerProvider, getStatusInfo: () => status }} />);
+    const input = screen.getByRole("textbox");
+    await user.click(input);
+    await user.type(input, "reports");
+    const link = await screen.findByRole("link", { name: status.label });
+    expect(link).toHaveAttribute("tabindex", "-1");
+    expect(link.querySelector("svg")).toBeNull();
+    expect(loadDetails).not.toHaveBeenCalled();
+    const selection = input.getAttribute("aria-activedescendant");
+    await user.click(link);
+    expect(await screen.findByRole("dialog", { name: "Directory Search Status" })).toBeInTheDocument();
+    expect(await screen.findByText("private")).toBeInTheDocument();
+    expect(screen.getByText("Access denied")).toBeInTheDocument();
+    expect(screen.getByText("Only some affected directories are listed.")).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Close" }));
+    await waitFor(() => expect(input).toHaveFocus());
+    expect(input).toHaveValue("reports");
+    expect(input.getAttribute("aria-activedescendant")).toBe(selection);
+    expect(screen.getByRole("option", { name: "Documents" })).toBeInTheDocument();
+  });
+
+  it.each(["stale", "failed"])("shows %s details without losing the quick-bar query", async (outcome) => {
+    const user = userEvent.setup();
+    const status = {
+      label: "FS1: not all directories could be indexed.",
+      showSpinner: false,
+      loadDetails:
+        outcome === "stale"
+          ? async () => ({ source: "FS1", issues: [] })
+          : async () => {
+              throw new Error("Disconnected");
+            },
+    };
+    renderWithProvider(<UnifiedSearchBar provider={{ ...footerProvider, getStatusInfo: () => status }} />);
+    const input = screen.getByRole("textbox");
+    await user.click(input);
+    await user.type(input, "reports");
+    await user.click(await screen.findByRole("link", { name: status.label }));
+    const message =
+      outcome === "stale"
+        ? "These details are no longer available. Refresh the status."
+        : "Could not load status details. Check the source connection and reopen this dialog.";
+    expect(await screen.findByText(message)).toBeInTheDocument();
+    await user.keyboard("{Escape}");
+    await waitFor(() => expect(input).toHaveFocus());
+    expect(input).toHaveValue("reports");
+  });
+
+  it("leaves statuses without additional information as plain text", async () => {
+    const user = userEvent.setup();
+    const status = { label: "FS1: not all directories could be indexed.", showSpinner: false };
+    renderWithProvider(<UnifiedSearchBar provider={{ ...footerProvider, getStatusInfo: () => status }} />);
+    await user.click(screen.getByRole("textbox"));
+    await user.type(screen.getByRole("textbox"), "reports");
+    expect(await screen.findByText(status.label)).toBeInTheDocument();
+    expect(screen.queryByRole("link")).not.toBeInTheDocument();
+    await user.click(screen.getByText(status.label));
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+  });
+
   it("publishes selectable rows before the final response and rejects old-query updates", async () => {
     const user = userEvent.setup();
     const updates = new Map<string, SearchResultsUpdate>();
@@ -1005,6 +1078,168 @@ describe("UnifiedSearchBar", () => {
     });
   });
 
+  it("fetches file history when the source updates during first activation", async () => {
+    const searchRecentFiles = vi.spyOn(browserHistoryService, "searchRecentFiles").mockResolvedValue({ results: [], result_limit: 50 });
+    const initialFiles: FileEntry[] = [];
+    const loadedFiles = [{ name: "report.txt", type: FileType.FILE }] as FileEntry[];
+    function SearchHarness({ active }: { active: boolean }) {
+      const fileProvider = useFileSearchProvider({
+        connectionId: "connection-1",
+        currentPath: "",
+        files: active ? loadedFiles : initialFiles,
+        connectionName: "Demo",
+        resultLimit: 50,
+        getConnectionName: () => "Demo",
+        onOpenCurrentFile: vi.fn(),
+        onOpenRecentFile: vi.fn(),
+      });
+      return <UnifiedSearchBar provider={active ? fileProvider : resultsProvider} activationToken={active ? 1 : 0} />;
+    }
+    const { rerender } = renderWithProvider(<SearchHarness active={false} />);
+
+    rerender(
+      <SambeeThemeProvider>
+        <SearchHarness active />
+      </SambeeThemeProvider>
+    );
+    await act(async () => screen.getByRole("textbox").focus());
+
+    expect(await screen.findByRole("option", { name: /report.txt/ })).toBeInTheDocument();
+    expect(searchRecentFiles).toHaveBeenCalledTimes(1);
+  });
+
+  it("waits for file history before opening the initial file-search menu", async () => {
+    const user = userEvent.setup();
+    let releaseHistory = () => {};
+    vi.spyOn(browserHistoryService, "searchRecentFiles").mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          releaseHistory = () => resolve({ results: [], result_limit: 50 });
+        })
+    );
+    const files = [{ name: "report.txt", type: FileType.FILE }] as FileEntry[];
+    function SearchHarness() {
+      const provider = useFileSearchProvider({
+        connectionId: "connection-1",
+        currentPath: "",
+        files,
+        connectionName: "Demo",
+        resultLimit: 50,
+        getConnectionName: () => "Demo",
+        onOpenCurrentFile: vi.fn(),
+        onOpenRecentFile: vi.fn(),
+      });
+      return <UnifiedSearchBar provider={provider} />;
+    }
+    renderWithProvider(<SearchHarness />);
+
+    await user.click(screen.getByRole("textbox"));
+    expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
+
+    await act(async () => releaseHistory());
+    expect(await screen.findByRole("option", { name: /report.txt/ })).toBeInTheDocument();
+  });
+
+  it("starts one search when shortcut activation is followed by input focus", async () => {
+    const fetchResults = vi.fn<SearchProvider["fetchResults"]>(() => new Promise<[]>(() => {}));
+    const onActivate = vi.fn();
+    const provider = { ...resultsProvider, fetchResults, onActivate };
+    const { rerender } = renderWithProvider(<UnifiedSearchBar provider={provider} activationToken={0} />);
+
+    rerender(
+      <SambeeThemeProvider>
+        <UnifiedSearchBar provider={provider} activationToken={1} />
+      </SambeeThemeProvider>
+    );
+    await act(async () => screen.getByRole("textbox").focus());
+
+    expect(onActivate).toHaveBeenCalledTimes(1);
+    expect(fetchResults).toHaveBeenCalledTimes(1);
+    expect(onActivate.mock.invocationCallOrder[0]).toBeLessThan(fetchResults.mock.invocationCallOrder[0] ?? 0);
+    expect(fetchResults.mock.calls[0]?.[1]?.aborted).toBe(false);
+  });
+
+  it.each(["suppressDropdown", "disableDropdown"] as const)("preserves the query when %s is cleared", async (prop) => {
+    const user = userEvent.setup();
+    const fetchResults = vi.fn<SearchProvider["fetchResults"]>(async (query) => [
+      {
+        kind: "result",
+        id: query || "all-commands",
+        value: query || "all-commands",
+        icon: "command",
+        primaryText: query || "All commands",
+      },
+    ]);
+    const provider = { ...commandsProvider, fetchResults };
+    const { rerender } = renderWithProvider(<UnifiedSearchBar provider={provider} />);
+
+    await user.click(screen.getByRole("textbox"));
+    await user.type(screen.getByRole("textbox"), "rename");
+    expect(await screen.findByRole("option", { name: "rename" })).toBeInTheDocument();
+
+    rerender(
+      <SambeeThemeProvider>
+        <UnifiedSearchBar provider={provider} {...{ [prop]: true }} />
+      </SambeeThemeProvider>
+    );
+    expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
+    fetchResults.mockClear();
+
+    rerender(
+      <SambeeThemeProvider>
+        <UnifiedSearchBar provider={provider} {...{ [prop]: false }} />
+      </SambeeThemeProvider>
+    );
+
+    expect(await screen.findByRole("option", { name: "rename" })).toBeInTheDocument();
+    expect(screen.getByRole("textbox")).toHaveValue("rename");
+    expect(fetchResults).toHaveBeenCalledTimes(1);
+    expect(fetchResults.mock.calls[0]?.[0]).toBe("rename");
+  });
+
+  it.each([
+    { grouped: false, shortcut: true, close: true },
+    { grouped: true, shortcut: true, close: true },
+    { grouped: false, shortcut: false, close: true },
+    { grouped: true, shortcut: false, close: true },
+    { grouped: false, shortcut: true, close: false },
+    { grouped: true, shortcut: true, close: false },
+  ])("resets results on activation (grouped: $grouped, shortcut: $shortcut, close: $close)", async ({ grouped, shortcut, close }) => {
+    const user = userEvent.setup();
+    const groupedProvider = createGroupedProvider(vi.fn());
+    const provider = {
+      ...groupedProvider,
+      fetchResults: async (query: string, signal: AbortSignal) =>
+        (await groupedProvider.fetchResults(query, signal)).filter((result) => grouped || result.kind === "result"),
+    };
+    const { rerender } = renderWithProvider(<UnifiedSearchBar provider={provider} activationToken={0} />);
+    const searchInput = screen.getByRole("textbox");
+
+    await user.click(searchInput);
+    expect(await screen.findByRole("option", { name: /Quarterly report/ })).toHaveAttribute("aria-selected", "true");
+    await user.keyboard("{ArrowDown}");
+    expect(screen.getByRole("option", { name: /Annual report/ })).toHaveAttribute("aria-selected", "true");
+    if (close) {
+      await user.keyboard("{Escape}");
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
+    }
+    virtualizerScrollToOffset.mockClear();
+
+    if (shortcut) {
+      rerender(
+        <SambeeThemeProvider>
+          <UnifiedSearchBar provider={provider} activationToken={1} />
+        </SambeeThemeProvider>
+      );
+    } else {
+      fireEvent.blur(searchInput);
+      fireEvent.focus(searchInput);
+    }
+
+    expect(await screen.findByRole("option", { name: /Quarterly report/ })).toHaveAttribute("aria-selected", "true");
+    expect(virtualizerScrollToOffset).toHaveBeenCalledWith(0);
+  });
+
   it("reopens the commands dropdown when the same mode is reactivated from outside the quick bar", async () => {
     const user = userEvent.setup();
 
diff --git a/frontend/src/components/FileBrowser/search/__tests__/useDirectorySearchProvider.test.ts b/frontend/src/components/FileBrowser/search/__tests__/useDirectorySearchProvider.test.ts
index b8eb6d34..1832b03d 100644
--- a/frontend/src/components/FileBrowser/search/__tests__/useDirectorySearchProvider.test.ts
+++ b/frontend/src/components/FileBrowser/search/__tests__/useDirectorySearchProvider.test.ts
@@ -20,10 +20,68 @@ function wrapper({ children }: { children: ReactNode }) {
 }
 
 describe("getDirectoryResultPresentation", () => {
+  it.each([false, true])("links named partial coverage only when details exist (%s)", async (available) => {
+    vi.mocked(api.searchRecentDirectories).mockResolvedValue({ result_limit: 10, results: [] });
+    const response = {
+      results: ["readable"],
+      total_matches: 1,
+      directory_count: 2,
+      cache_state: "ready" as const,
+      coverage: "partial" as const,
+      coverage_issue_count: 1,
+      issue_details_available: available,
+      search_contract_version: SEARCH_CONTRACT_VERSION,
+    };
+    vi.mocked(api.searchDirectories).mockResolvedValue(response);
+    const { result } = renderHook(() => useDirectorySearchProvider("local-C", vi.fn(), { getConnectionName: () => "FS1" }), { wrapper });
+    await act(async () => {
+      await result.current.fetchResults("readable", new AbortController().signal);
+    });
+    const status = result.current.getStatusInfo();
+    expect(status).toMatchObject({ label: "FS1: not all directories could be indexed.", showSpinner: false });
+    expect(!!status?.loadDetails).toBe(available);
+    if (available) {
+      vi.mocked(api.searchDirectories).mockResolvedValue({
+        ...response,
+        issue_details: [{ path: "private", code: "access_denied" }],
+        issue_details_incomplete: true,
+      });
+      const signal = new AbortController().signal;
+      await expect(status?.loadDetails?.(signal)).resolves.toEqual({
+        source: "FS1",
+        issues: [{ path: "private", code: "access_denied" }],
+        incomplete: true,
+      });
+      expect(api.searchDirectories).toHaveBeenLastCalledWith("local-C", "", {
+        includeDotDirectories: false,
+        includeIssueDetails: true,
+        signal,
+      });
+    }
+  });
+
+  it("does not attach history error details to an index failure", async () => {
+    vi.mocked(api.searchRecentDirectories).mockRejectedValue(new Error("History storage is offline."));
+    vi.mocked(api.searchDirectories).mockRejectedValue({
+      response: { status: 403, data: { detail: { message: "This source is not permitted." } } },
+    });
+    const { result } = renderHook(() => useDirectorySearchProvider("connection-1", vi.fn(), { getConnectionName: () => "FS1" }), {
+      wrapper,
+    });
+    await act(async () => {
+      await result.current.fetchResults("reports", new AbortController().signal);
+    });
+    await expect(result.current.getStatusInfo()?.loadDetails?.(new AbortController().signal)).resolves.toEqual({
+      source: "FS1",
+      message: "This source is not permitted.",
+    });
+  });
+
   it.each([
-    { phase: "building", label: "Indexing... (123 directories found)" },
-    { phase: "updating", label: "Updating index... (12 of ~42 directories checked)" },
-  ] as const)("shows $phase progress before uncertain coverage", async ({ phase, label }) => {
+    { phase: "building", found: 0, label: "Indexing..." },
+    { phase: "building", found: 123, label: "Indexing... (123 directories found)" },
+    { phase: "updating", found: 123, label: "Updating index... (12 of ~42 directories checked)" },
+  ] as const)("shows $phase progress before uncertain coverage", async ({ phase, found, label }) => {
     vi.mocked(api.searchRecentDirectories).mockResolvedValue({ result_limit: 10, results: [] });
     vi.mocked(api.searchDirectories).mockResolvedValue({
       results: [],
@@ -32,16 +90,80 @@ describe("getDirectoryResultPresentation", () => {
       directory_count: 7,
       coverage: "uncertain",
       search_contract_version: SEARCH_CONTRACT_VERSION,
-      scan_progress: { phase, parents_done: 12, parents_queued: 30, directories_found: 123, started_at_ms: 1 },
+      scan_progress: { phase, parents_done: 12, parents_queued: 30, directories_found: found, started_at_ms: 1 },
     });
     const { result } = renderHook(() => useDirectorySearchProvider("connection-1", vi.fn()), { wrapper });
     await act(async () => {
       await result.current.fetchResults("reports", new AbortController().signal);
     });
-    expect(result.current.getStatusInfo()).toEqual({ label, showSpinner: true });
+    expect(result.current.getStatusInfo()).toEqual({ label: `connection-1: ${label}`, showSpinner: true });
     expect(result.current.getRefreshIntervalMs?.()).toBe(500);
   });
 
+  it.each([
+    { cache_state: "building", directory_count: 0, label: "Indexing...", spinner: true },
+    { cache_state: "building", directory_count: 3, label: "Indexing... (3 directories found)", spinner: true },
+    { cache_state: "updating", directory_count: 3, label: "Updating index... (3 directories)", spinner: true },
+    { cache_state: "ready", directory_count: 3, label: null, spinner: false },
+  ] as const)(
+    "keeps opening silent before $cache_state with $directory_count directories",
+    async ({ cache_state, directory_count, label, spinner }) => {
+      vi.mocked(api.searchRecentDirectories).mockResolvedValue({ result_limit: 10, results: [] });
+      vi.mocked(api.searchDirectories).mockResolvedValue({
+        results: [],
+        total_matches: 0,
+        cache_state: "opening",
+        directory_count: 0,
+        coverage: "partial",
+        search_contract_version: SEARCH_CONTRACT_VERSION,
+      });
+      const { result } = renderHook(() => useDirectorySearchProvider("connection-1", vi.fn()), { wrapper });
+      expect(result.current.getStatusInfo()).toBeNull();
+      await act(async () => {
+        await result.current.fetchResults("reports", new AbortController().signal);
+      });
+      expect(result.current.getStatusInfo()).toBeNull();
+      expect(result.current.getRefreshIntervalMs?.()).toBe(500);
+      vi.mocked(api.searchDirectories).mockResolvedValue({
+        results: [],
+        total_matches: 0,
+        cache_state,
+        directory_count,
+        coverage: "complete",
+        search_contract_version: SEARCH_CONTRACT_VERSION,
+      });
+      await act(async () => {
+        await result.current.fetchResults("reports", new AbortController().signal);
+      });
+      expect(result.current.getStatusInfo()).toEqual(label ? { label: `connection-1: ${label}`, showSpinner: spinner } : null);
+    }
+  );
+
+  it("shows a recovery message even while opening", async () => {
+    vi.mocked(api.searchRecentDirectories).mockResolvedValue({ result_limit: 10, results: [] });
+    const message = "Directory index storage is in use. Wait for active workers to finish, then retry.";
+    vi.mocked(api.searchDirectories).mockResolvedValue({
+      results: [],
+      total_matches: 0,
+      cache_state: "opening",
+      directory_count: 0,
+      status_message: message,
+      retry_after_ms: 2000,
+      search_contract_version: SEARCH_CONTRACT_VERSION,
+    });
+    const { result } = renderHook(() => useDirectorySearchProvider("connection-1", vi.fn()), { wrapper });
+    await act(async () => {
+      await result.current.fetchResults("reports", new AbortController().signal);
+    });
+    expect(result.current.getStatusInfo()).toEqual({ label: `connection-1: ${message}`, showSpinner: false });
+    expect(result.current.getRefreshIntervalMs?.()).toBe(2000);
+    vi.mocked(api.searchDirectories).mockRejectedValue(new Error("Source is offline."));
+    await act(async () => {
+      await result.current.fetchResults("reports", new AbortController().signal);
+    });
+    expect(result.current.getStatusInfo()?.label).toContain("Directory search is unavailable");
+  });
+
   it.each(["connection-1", "local-C"])("fences old generation responses and retry errors for %s", async (connectionId) => {
     type Response = Awaited<ReturnType<typeof api.searchDirectories>>;
     const services = createBrowserContentServices([], new CompanionSession());
@@ -168,10 +290,11 @@ describe("getDirectoryResultPresentation", () => {
       await result.current.fetchResults("reports", new AbortController().signal);
     });
     expect(commits).toBeGreaterThan(settledCommits);
-    expect(result.current.getStatusInfo?.()).toEqual({ label: statusMessage, showSpinner: false });
+    expect(result.current.getStatusInfo?.()).toEqual({ label: `connection-1: ${statusMessage}`, showSpinner: false });
   });
 
   it.each([
+    { cache_state: "opening", search_contract_version: SEARCH_CONTRACT_VERSION, expected: 500 },
     { cache_state: "building", search_contract_version: SEARCH_CONTRACT_VERSION, expected: 500 },
     { cache_state: "updating", search_contract_version: SEARCH_CONTRACT_VERSION, expected: 500 },
     { cache_state: "ready", search_contract_version: SEARCH_CONTRACT_VERSION, expected: null },
@@ -245,8 +368,7 @@ describe("getDirectoryResultPresentation", () => {
     expect(api.searchDirectories).toHaveBeenCalledWith(connectionId, "alpha beta", expect.objectContaining({ signal: expect.anything() }));
     expect(rows.some((row) => row.kind === "result" && row.value === "directory:alpha/beta")).toBe(true);
     expect(result.current.getStatusInfo?.()).toEqual({
-      label:
-        "Multi-term directory search is not confirmed for this source. Search one directory term or check backend and companion support.",
+      label: `${connectionId}: Multi-term directory search is not confirmed for this source. Search one directory term or check backend and companion support.`,
       showSpinner: false,
     });
     vi.mocked(api.searchDirectories).mockResolvedValue({ ...response, search_contract_version: SEARCH_CONTRACT_VERSION });
@@ -352,7 +474,7 @@ describe("getDirectoryResultPresentation", () => {
     });
     expect(rows.some((row) => row.kind === "result" && row.value === "directory:Reports")).toBe(true);
     expect(result.current.getStatusInfo?.()).toEqual({
-      label: "Directory indexing is paused. Increase its disk budget and retry.",
+      label: "connection-1: Directory indexing is paused. Increase its disk budget and retry.",
       showSpinner: false,
     });
   });
diff --git a/frontend/src/components/FileBrowser/search/__tests__/useFileSearchProvider.test.tsx b/frontend/src/components/FileBrowser/search/__tests__/useFileSearchProvider.test.tsx
index 78a0eeea..3c451252 100644
--- a/frontend/src/components/FileBrowser/search/__tests__/useFileSearchProvider.test.tsx
+++ b/frontend/src/components/FileBrowser/search/__tests__/useFileSearchProvider.test.tsx
@@ -56,9 +56,10 @@ describe("useFileSearchProvider", () => {
       await pending;
     });
     expect(await pending).toEqual(onUpdate.mock.calls[0]?.[0]);
-    expect(result.current.getStatusInfo()).toEqual({
-      label: "Recent files are unavailable. Check the backend connection and retry.",
+    expect(result.current.getStatusInfo()).toMatchObject({
+      label: "Reports server: Recent files are unavailable. Check the backend connection and retry.",
       showSpinner: false,
+      loadDetails: expect.any(Function),
     });
   });
 
diff --git a/frontend/src/components/FileBrowser/search/recentHistory.ts b/frontend/src/components/FileBrowser/search/recentHistory.ts
index 2da80028..7c0c3219 100644
--- a/frontend/src/components/FileBrowser/search/recentHistory.ts
+++ b/frontend/src/components/FileBrowser/search/recentHistory.ts
@@ -7,6 +7,22 @@ export const SEARCH_CONTRACT_VERSION = 1;
 const NORMALIZATION_KEYS = new Map(unicode.normalization.map(([source, key]) => [source ?? "", key ?? ""]));
 const QUERY_WHITESPACE = new Set(unicode.whitespace);
 
+export function getSearchErrorMessage(error: unknown): string | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  const response = "response" in error ? error.response : undefined;
+  const data = response && typeof response === "object" && "data" in response ? response.data : undefined;
+  const detail = data && typeof data === "object" && "detail" in data ? data.detail : undefined;
+  const message =
+    typeof detail === "string"
+      ? detail
+      : detail && typeof detail === "object" && "message" in detail
+        ? detail.message
+        : error instanceof Error
+          ? error.message
+          : undefined;
+  return typeof message === "string" && message.trim() ? message.trim() : undefined;
+}
+
 function isWordCharacter(character: string): boolean {
   const codepoint = character.codePointAt(0) ?? -1;
   let low = 0;
diff --git a/frontend/src/components/FileBrowser/search/types.ts b/frontend/src/components/FileBrowser/search/types.ts
index bfc32985..0bbaf22f 100644
--- a/frontend/src/components/FileBrowser/search/types.ts
+++ b/frontend/src/components/FileBrowser/search/types.ts
@@ -74,11 +74,19 @@ export type SearchResult = SearchResultItem | SearchResultGroupHeader;
 export type SearchResultsUpdate = (results: SearchResult[]) => void;
 
 /** Status information from the provider (e.g., indexing progress) */
+export interface SearchStatusDetails {
+  source: string;
+  message?: string;
+  issues?: import("../../../types").DirectoryIssueDetail[];
+  incomplete?: boolean;
+}
+
 export interface SearchStatusInfo {
   /** Short text label describing current status */
   label: string;
   /** Whether an activity spinner should be shown */
   showSpinner: boolean;
+  loadDetails?: (signal: AbortSignal) => Promise<SearchStatusDetails>;
 }
 
 export type SearchSelectionFocusTarget = "file-list" | "quick-bar" | "none";
diff --git a/frontend/src/components/FileBrowser/search/useDirectorySearchProvider.tsx b/frontend/src/components/FileBrowser/search/useDirectorySearchProvider.tsx
index 8f785b6e..619d1a00 100644
--- a/frontend/src/components/FileBrowser/search/useDirectorySearchProvider.tsx
+++ b/frontend/src/components/FileBrowser/search/useDirectorySearchProvider.tsx
@@ -28,6 +28,7 @@ import {
   bestSearchRelevance,
   findSearchHighlights,
   findTextHighlight,
+  getSearchErrorMessage,
   getSearchRelevance,
   rankHistorySearchResults,
   removeRecentHistoryResult,
@@ -232,14 +233,22 @@ export function useDirectorySearchProvider(
   options: DirectorySearchProviderOptions = {}
 ): SearchProvider {
   const { t } = useTranslation();
-  const [cacheState, setCacheState] = useState<string>("empty");
+  const [cacheState, setCacheState] = useState<string>("opening");
   const [directoryCount, setDirectoryCount] = useState(0);
   const [totalMatches, setTotalMatches] = useState(0);
   const [coverageStatus, setCoverageStatus] = useState<Pick<
     DirectorySearchResult,
-    "coverage" | "coverage_issue_count" | "last_verified_at_ms" | "status_message" | "monitoring_state" | "retry_after_ms" | "scan_progress"
+    | "coverage"
+    | "coverage_issue_count"
+    | "last_verified_at_ms"
+    | "status_message"
+    | "monitoring_state"
+    | "retry_after_ms"
+    | "scan_progress"
+    | "issue_details_available"
   > | null>(null);
   const [sourceFailure, setSourceFailure] = useState<"history" | "index" | null>(null);
+  const [failureDetail, setFailureDetail] = useState<string | undefined>();
   const [legacyIndex, setLegacyIndex] = useState(false);
   const indexFailureRef = useRef(false);
   const indexResponseRef = useRef<DirectorySearchResult | null>(null);
@@ -264,6 +273,7 @@ export function useDirectorySearchProvider(
     setCoverageStatus((previous) =>
       previous?.coverage === response.coverage &&
       previous?.coverage_issue_count === response.coverage_issue_count &&
+      previous?.issue_details_available === response.issue_details_available &&
       previous?.last_verified_at_ms === response.last_verified_at_ms &&
       previous?.status_message === response.status_message &&
       previous?.monitoring_state === response.monitoring_state &&
@@ -277,6 +287,7 @@ export function useDirectorySearchProvider(
         : {
             coverage: response.coverage,
             coverage_issue_count: response.coverage_issue_count,
+            issue_details_available: response.issue_details_available,
             last_verified_at_ms: response.last_verified_at_ms,
             status_message: response.status_message,
             monitoring_state: response.monitoring_state,
@@ -297,7 +308,8 @@ export function useDirectorySearchProvider(
     terminalIndexRef.current = false;
     indexFailureRef.current = false;
     setSourceFailure(null);
-    setCacheState("empty");
+    setFailureDetail(undefined);
+    setCacheState("opening");
     setCoverageStatus(null);
     return () => {
       requestGenerationRef.current += 1;
@@ -447,6 +459,15 @@ export function useDirectorySearchProvider(
         retryDelayRef.current = failure.delay;
       }
       setSourceFailure(indexFailureRef.current ? "index" : recentOutcome.status === "rejected" ? "history" : null);
+      setFailureDetail((previous) =>
+        indexOutcome.status === "rejected"
+          ? getSearchErrorMessage(indexOutcome.reason)
+          : indexFailureRef.current
+            ? previous
+            : recentOutcome.status === "rejected"
+              ? getSearchErrorMessage(recentOutcome.reason)
+              : undefined
+      );
       return mergeResults();
     },
     [
@@ -508,12 +529,15 @@ export function useDirectorySearchProvider(
       };
     }
     if (coverageStatus?.status_message) return { label: coverageStatus.status_message, showSpinner: !!working };
+    if (cacheState === "opening") return null;
     const progress = coverageStatus?.scan_progress;
     if (progress && progress.phase !== "idle") {
       return {
         label:
           progress.phase === "building"
-            ? t("fileBrowser.search.status.indexing", { count: progress.directories_found })
+            ? progress.directories_found > 0
+              ? t("fileBrowser.search.status.indexing", { count: progress.directories_found })
+              : t("fileBrowser.search.status.indexingPending")
             : t("fileBrowser.search.status.updatingProgress", {
                 done: progress.parents_done,
                 total: progress.parents_done + progress.parents_queued,
@@ -532,7 +556,10 @@ export function useDirectorySearchProvider(
     switch (cacheState) {
       case "building":
         return {
-          label: t("fileBrowser.search.status.indexing", { count: directoryCount }),
+          label:
+            directoryCount > 0
+              ? t("fileBrowser.search.status.indexing", { count: directoryCount })
+              : t("fileBrowser.search.status.indexingPending"),
           showSpinner: !!working,
         };
       case "updating":
@@ -556,7 +583,8 @@ export function useDirectorySearchProvider(
     if (!response || response.search_contract_version !== SEARCH_CONTRACT_VERSION) return null;
     if (response.retry_after_ms != null && response.retry_after_ms > 0) return directoryRetryDelay(response.retry_after_ms);
     if (response.scan_progress && response.scan_progress.phase !== "idle") return DIRECTORY_REFRESH_INTERVAL_MS;
-    if (response.cache_state === "building" || response.cache_state === "updating") return DIRECTORY_REFRESH_INTERVAL_MS;
+    if (response.cache_state === "opening" || response.cache_state === "building" || response.cache_state === "updating")
+      return DIRECTORY_REFRESH_INTERVAL_MS;
     return response.cache_state === "empty" ||
       response.status_message ||
       response.coverage === "uncertain" ||
@@ -586,6 +614,7 @@ export function useDirectorySearchProvider(
           indexResponseRef.current = result;
           indexFailureRef.current = false;
           setSourceFailure(null);
+          setFailureDetail(undefined);
           terminalIndexRef.current = result.search_contract_version != null && result.search_contract_version !== SEARCH_CONTRACT_VERSION;
           updateIndexStatus(result);
         }
@@ -597,6 +626,7 @@ export function useDirectorySearchProvider(
           retryDelayRef.current = failure.delay;
           indexFailureRef.current = true;
           setSourceFailure("index");
+          setFailureDetail(getSearchErrorMessage(error));
           logger.warn("Directory cache activation is unavailable", {}, "directory-search-provider");
         }
       });
@@ -641,7 +671,36 @@ export function useDirectorySearchProvider(
     fetchResults,
     onSelect,
     onRemoveSelected,
-    getStatusInfo,
+    getStatusInfo: () => {
+      const status = getStatusInfo();
+      if (!status) return null;
+      const source = options.getConnectionName?.(connectionId) ?? connectionId;
+      const partial = coverageStatus?.coverage === "partial" && cacheState === "ready" && !sourceFailure && !coverageStatus.status_message;
+      return {
+        ...status,
+        label: t("fileBrowser.search.status.connectionStatus", {
+          connection: source,
+          message: partial ? t("fileBrowser.search.status.indexCoveragePartial") : status.label,
+        }),
+        ...(partial && coverageStatus.issue_details_available
+          ? {
+              loadDetails: async (signal: AbortSignal) => {
+                const response = await history.searchDirectories(connectionId, "", {
+                  includeDotDirectories,
+                  includeIssueDetails: true,
+                  signal,
+                });
+                return { source, issues: response.issue_details ?? [], incomplete: response.issue_details_incomplete };
+              },
+            }
+          : {}),
+        ...(sourceFailure && failureDetail && failureDetail !== status.label
+          ? {
+              loadDetails: async () => ({ source, message: failureDetail }),
+            }
+          : {}),
+      };
+    },
     getRefreshIntervalMs,
     invalidateResults: () => {
       recentResponseRef.current = null;
diff --git a/frontend/src/components/FileBrowser/search/useFileSearchProvider.tsx b/frontend/src/components/FileBrowser/search/useFileSearchProvider.tsx
index e52ec1dd..2825bf7f 100644
--- a/frontend/src/components/FileBrowser/search/useFileSearchProvider.tsx
+++ b/frontend/src/components/FileBrowser/search/useFileSearchProvider.tsx
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import type { BrowserOpenMode } from "../../../pages/FileBrowser/types";
 import { type BrowserHistoryService, browserHistoryService } from "../../../services/browserHistoryService";
@@ -8,6 +8,7 @@ import {
   bestSearchRelevance,
   compareText,
   findTextHighlight,
+  getSearchErrorMessage,
   getSearchRelevance,
   normalizeSearchText,
   rankHistorySearchResults,
@@ -62,8 +63,9 @@ export function useFileSearchProvider({
   const requestGenerationRef = useRef(0);
   const sourceBindingRef = useRef({ connectionId, currentPath, files, history, resultLimit });
   const [historyUnavailable, setHistoryUnavailable] = useState(false);
+  const [failureDetail, setFailureDetail] = useState<string | undefined>();
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     sourceBindingRef.current = { connectionId, currentPath, files, history, resultLimit };
     return () => {
       requestGenerationRef.current += 1;
@@ -85,6 +87,7 @@ export function useFileSearchProvider({
         sourceBindingRef.current.resultLimit === resultLimit;
       if (!isCurrent()) return [];
       setHistoryUnavailable(false);
+      setFailureDetail(undefined);
       const terms = searchTerms(query);
       const currentCandidates = files
         .filter((file) => file.type === "file" && (!terms.length || getSearchRelevance(file.name, terms).matchedTermCount > 0))
@@ -170,16 +173,16 @@ export function useFileSearchProvider({
         );
       };
       const availableResponse: RecentFileSearchResponse = { results: [], result_limit: resultLimit };
-      const availableResults = mergeResults(availableResponse);
-      onUpdate?.(availableResults);
+      if (terms.length > 0) onUpdate?.(mergeResults(availableResponse));
       try {
         const recentResponse = await history.searchRecentFiles(query, resultLimit, signal);
         if (!isCurrent()) return [];
         return mergeResults(recentResponse);
-      } catch {
+      } catch (error: unknown) {
         if (!isCurrent()) return [];
         setHistoryUnavailable(true);
-        return availableResults;
+        setFailureDetail(getSearchErrorMessage(error));
+        return mergeResults(availableResponse);
       }
     },
     [connectionId, connectionName, currentPath, files, getConnectionName, history, resultLimit, t]
@@ -201,8 +204,21 @@ export function useFileSearchProvider({
 
   const getStatusInfo = useCallback(
     (): SearchStatusInfo | null =>
-      historyUnavailable ? { label: t("fileBrowser.search.status.fileHistoryUnavailable"), showSpinner: false } : null,
-    [historyUnavailable, t]
+      historyUnavailable
+        ? {
+            label: t("fileBrowser.search.status.connectionStatus", {
+              connection: connectionName,
+              message: t("fileBrowser.search.status.fileHistoryUnavailable"),
+            }),
+            showSpinner: false,
+            ...(failureDetail && failureDetail !== t("fileBrowser.search.status.fileHistoryUnavailable")
+              ? {
+                  loadDetails: async () => ({ source: connectionName, message: failureDetail }),
+                }
+              : {}),
+          }
+        : null,
+    [connectionName, failureDetail, historyUnavailable, t]
   );
 
   const onRemoveSelected = useCallback(
diff --git a/frontend/src/components/Settings/CompanionPolicyDelivery.tsx b/frontend/src/components/Settings/CompanionPolicyDelivery.tsx
index 545655c7..5fd3d52b 100644
--- a/frontend/src/components/Settings/CompanionPolicyDelivery.tsx
+++ b/frontend/src/components/Settings/CompanionPolicyDelivery.tsx
@@ -20,8 +20,8 @@ export function CompanionPolicyDelivery() {
   const { t } = useTranslation();
   const snapshot = useCompanionSettingsSync();
   const busy = snapshot.phase === "synchronizing";
-  const failed = snapshot.phase === "delivery_failed";
-  const warning = failed || snapshot.phase === "authority_conflict" || snapshot.phase === "update_required";
+  const needsRetry = snapshot.phase === "delivery_failed" || snapshot.phase === "pairing_required";
+  const warning = needsRetry || snapshot.phase === "authority_conflict" || snapshot.phase === "update_required";
   const phaseLabel = (phase: SettingsSyncPhase) => t(`settings.companionSync.${phase}`);
   return (
     <FormSurface testId="companion-settings-surface">
@@ -47,7 +47,7 @@ export function CompanionPolicyDelivery() {
             disabled={busy}
             onClick={() => companionSettingsSync.request(false, true)}
           >
-            {t(failed ? "common.actions.retry" : "settings.directorySearch.refresh")}
+            {t(needsRetry ? "common.actions.retry" : "settings.directorySearch.refresh")}
           </Button>
         </Box>
       </FormRow>
diff --git a/frontend/src/components/Settings/__tests__/CompanionPolicyDelivery.test.tsx b/frontend/src/components/Settings/__tests__/CompanionPolicyDelivery.test.tsx
index 1e8678eb..8639506f 100644
--- a/frontend/src/components/Settings/__tests__/CompanionPolicyDelivery.test.tsx
+++ b/frontend/src/components/Settings/__tests__/CompanionPolicyDelivery.test.tsx
@@ -36,6 +36,16 @@ describe("Companion shared synchronization status", () => {
     expect(request).toHaveBeenCalledExactlyOnceWith(false, true);
   });
 
+  it("shows pairing recovery instructions instead of a delivery failure", async () => {
+    snapshot.phase = "pairing_required";
+    render(<CompanionDirectoryStatus isAdmin={false} />);
+    expect(screen.getByText("Theme: Pairing required")).toBeInTheDocument();
+    expect(screen.getByRole("status")).toHaveTextContent("Pair this browser in Settings > Local Drives");
+    expect(screen.queryByText(/Delivery failed/)).not.toBeInTheDocument();
+    await userEvent.click(screen.getByRole("button", { name: "Retry" }));
+    expect(request).toHaveBeenCalledExactlyOnceWith(false, true);
+  });
+
   it("disables refresh during delivery and keeps notices inside the surface", () => {
     snapshot.phase = "synchronizing";
     render(<CompanionDirectoryStatus isAdmin={false} />);
@@ -43,16 +53,21 @@ describe("Companion shared synchronization status", () => {
     expect(screen.getByTestId("companion-settings-surface")).toContainElement(screen.getByRole("status"));
   });
 
-  it.each(["defaults_active", "synchronized", "synchronizing", "update_required", "authority_conflict", "delivery_failed"] as const)(
-    "keeps every %s state inside the shared surface",
-    (phase) => {
-      snapshot.phase = phase;
-      snapshot.sections = { theme: phase, localization: "synchronized", directory_index: "defaults_active" };
-      render(<CompanionDirectoryStatus isAdmin={false} />);
-      const surface = screen.getByTestId("companion-settings-surface");
-      expect(surface).toContainElement(screen.getByRole("status"));
-      expect(surface).toHaveTextContent("Localization: Synchronized");
-      expect(surface).toHaveTextContent("Directory search policy: Built-in defaults");
-    }
-  );
+  it.each([
+    "defaults_active",
+    "synchronized",
+    "synchronizing",
+    "update_required",
+    "authority_conflict",
+    "pairing_required",
+    "delivery_failed",
+  ] as const)("keeps every %s state inside the shared surface", (phase) => {
+    snapshot.phase = phase;
+    snapshot.sections = { theme: phase, localization: "synchronized", directory_index: "defaults_active" };
+    render(<CompanionDirectoryStatus isAdmin={false} />);
+    const surface = screen.getByTestId("companion-settings-surface");
+    expect(surface).toContainElement(screen.getByRole("status"));
+    expect(surface).toHaveTextContent("Localization: Synchronized");
+    expect(surface).toHaveTextContent("Directory search policy: Built-in defaults");
+  });
 });
diff --git a/frontend/src/i18n/resources.ts b/frontend/src/i18n/resources.ts
index 50790d92..2473133b 100644
--- a/frontend/src/i18n/resources.ts
+++ b/frontend/src/i18n/resources.ts
@@ -208,6 +208,7 @@ export const EN_TRANSLATIONS = {
         synchronizing: "Synchronizing",
         update_required: "Update required",
         authority_conflict: "Different settings authority",
+        pairing_required: "Pairing required",
         delivery_failed: "Delivery failed; last valid settings active",
       },
       defaults_active: "Built-in defaults are active until settings arrive from a paired server.",
@@ -215,6 +216,8 @@ export const EN_TRANSLATIONS = {
       synchronizing: "Settings are synchronizing. The last valid settings remain active.",
       update_required: "Update Sambee and Companion to use shared settings delivery.",
       authority_conflict: "This server does not manage Companion settings. Pair the intended server again to change authority.",
+      pairing_required:
+        "Companion could not authenticate this browser. Pair this browser in Settings > Local Drives, or pair it again to repair the connection. Settings checks are paused until you retry or pair successfully.",
       delivery_failed:
         "Settings delivery failed. Check the connection and retry. The last valid settings and directory search remain available.",
       authority: "Settings authority: {{origin}}",
@@ -772,11 +775,13 @@ export const EN_TRANSLATIONS = {
         directoriesIndexed_other: "{{count}} directories indexed",
       },
       status: {
+        connectionStatus: "{{connection}}: {{message}}",
+        indexingPending: "Indexing...",
         indexing: "Indexing... ({{count}} directories found)",
         updating: "Updating index... ({{count}} directories)",
         updatingProgress: "Updating index... ({{done}} of ~{{total}} directories checked)",
         startingIndex: "Starting index...",
-        indexCoveragePartial: "Directory index has incomplete coverage.",
+        indexCoveragePartial: "not all directories could be indexed.",
         indexCoverageUncertain: "Directory index is not verified. A new check is pending.",
         legacyDirectorySearch:
           "Multi-term directory search is not confirmed for this source. Search one directory term or check backend and companion support.",
@@ -784,6 +789,20 @@ export const EN_TRANSLATIONS = {
         fileHistoryUnavailable: "Recent files are unavailable. Check the backend connection and retry.",
         indexUnavailable: "Directory search is unavailable. Check the source connection and retry.",
       },
+      statusDetails: {
+        title: "Directory Search Status",
+        source: "Source",
+        impact: "Search results may not include directories within these locations.",
+        incomplete: "Only some affected directories are listed.",
+        unavailable: "These details are no longer available. Refresh the status.",
+        failed: "Could not load status details. Check the source connection and reopen this dialog.",
+        reasons: {
+          access_denied: "Access denied",
+          unsupported_encoding: "A directory name could not be read",
+          unsafe_traversal: "A directory could not be traversed safely",
+          scan_failed: "A directory could not be read",
+        },
+      },
       groups: {
         recentFiles: "Recent files",
         recentDirectories: "Recent directories",
diff --git a/frontend/src/services/__tests__/browseApi.test.ts b/frontend/src/services/__tests__/browseApi.test.ts
index 863a6554..e83af670 100644
--- a/frontend/src/services/__tests__/browseApi.test.ts
+++ b/frontend/src/services/__tests__/browseApi.test.ts
@@ -688,7 +688,7 @@ describe("Browse API Contract Tests", () => {
     });
 
     it("should accept all valid cache states", async () => {
-      const cacheStates = ["empty", "building", "ready", "updating"] as const;
+      const cacheStates = ["empty", "opening", "building", "ready", "updating"] as const;
 
       for (const state of cacheStates) {
         const backendResponse: DirectorySearchResult = {
diff --git a/frontend/src/services/__tests__/companionSettingsSync.test.ts b/frontend/src/services/__tests__/companionSettingsSync.test.ts
index d428af93..9aa40b60 100644
--- a/frontend/src/services/__tests__/companionSettingsSync.test.ts
+++ b/frontend/src/services/__tests__/companionSettingsSync.test.ts
@@ -11,9 +11,11 @@ const mocks = vi.hoisted(() => ({
   identity: null as null | (() => void),
   clear: null as null | (() => void),
   authenticated: true,
+  hasSecret: true,
 }));
 vi.mock("../api", () => ({ default: { getCompanionSettingsMetadata: mocks.metadata, issueCompanionSettingsGrant: mocks.grant } }));
-vi.mock("../companion", () => ({
+vi.mock("../companion", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../companion")>()),
   default: { getSettingsStatus: mocks.status, requestSettingsChallenge: mocks.challenge, redeemSettingsGrant: mocks.redeem },
 }));
 vi.mock("../authConfig", () => ({ isAuthRequired: async () => true }));
@@ -36,7 +38,7 @@ vi.mock("../authSession", () => ({
     subscribeToBootstrap: () => vi.fn(),
   },
 }));
-vi.mock("../companionSession", () => ({ companionSession: { hasSecret: () => true, subscribe: () => vi.fn() } }));
+vi.mock("../companionSession", () => ({ companionSession: { hasSecret: () => mocks.hasSecret, subscribe: () => vi.fn() } }));
 vi.mock("../logger", () => ({ logger: { initializeBackendTracing: vi.fn().mockResolvedValue(undefined) } }));
 
 import { emitBackendRecoveryConfirmed } from "../backendRecoveryEvents";
@@ -85,6 +87,7 @@ describe("shared Companion settings lifecycle", () => {
     vi.useFakeTimers();
     vi.clearAllMocks();
     mocks.authenticated = true;
+    mocks.hasSecret = true;
     vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
     mocks.metadata.mockResolvedValue(metadata());
     mocks.status.mockResolvedValue(status());
@@ -107,6 +110,45 @@ describe("shared Companion settings lifecycle", () => {
     expect(companionSettingsSync.getSnapshot().phase).toBe("synchronized");
   });
 
+  it("does not request settings without a stored pairing secret", async () => {
+    mocks.hasSecret = false;
+    companionSettingsSync.start();
+    await settle();
+    await vi.advanceTimersByTimeAsync(120_000);
+    expect(mocks.status).not.toHaveBeenCalled();
+    expect(mocks.metadata).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    { code: "companion_auth_signature_mismatch", detail: "Invalid authentication" },
+    { code: "companion_pairing_not_found", detail: "Not paired with this origin" },
+    { detail: "Invalid authentication" },
+    { detail: "Not paired with this origin" },
+  ])("blocks automatic retries after pairing failure: $detail ($code)", async (data) => {
+    mocks.status.mockRejectedValue({ response: { status: 403, data } });
+    companionSettingsSync.start();
+    await settle();
+
+    expect(companionSettingsSync.getSnapshot()).toMatchObject({ phase: "pairing_required", message: null });
+    window.dispatchEvent(new Event("online"));
+    document.dispatchEvent(new Event("visibilitychange"));
+    emitBackendRecoveryConfirmed("pairing-retry-test");
+    await vi.advanceTimersByTimeAsync(120_000);
+    expect(mocks.status).toHaveBeenCalledOnce();
+    expect(mocks.grant).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+
+    companionSettingsSync.request(false, true);
+    await settle();
+    expect(mocks.status).toHaveBeenCalledTimes(2);
+
+    mocks.status.mockResolvedValue(status());
+    notifyCompanionSettingsChanged(true);
+    await settle();
+    expect(mocks.status).toHaveBeenCalledTimes(3);
+    expect(companionSettingsSync.getSnapshot().phase).toBe("synchronized");
+  });
+
   it("delivers only a changed theme section", async () => {
     const native = status();
     native.sections.theme!.marker = "old";
diff --git a/frontend/src/services/api.ts b/frontend/src/services/api.ts
index 1c19d848..5870089c 100644
--- a/frontend/src/services/api.ts
+++ b/frontend/src/services/api.ts
@@ -91,6 +91,7 @@ const COMPANION_TIMING_OTHER_ROUTE = "/{route}";
 
 export interface DirectorySearchOptions {
   includeDotDirectories?: boolean;
+  includeIssueDetails?: boolean;
   signal?: AbortSignal;
 }
 
@@ -1592,6 +1593,7 @@ class ApiService {
       params: {
         q: query,
         include_dot_directories: options?.includeDotDirectories ?? false,
+        ...(options?.includeIssueDetails ? { include_issue_details: true } : {}),
       },
       signal: options?.signal,
     });
diff --git a/frontend/src/services/browserHistoryService.ts b/frontend/src/services/browserHistoryService.ts
index de12b335..590fcfaf 100644
--- a/frontend/src/services/browserHistoryService.ts
+++ b/frontend/src/services/browserHistoryService.ts
@@ -13,7 +13,7 @@ export interface BrowserHistoryService {
   searchDirectories(
     connectionId: string,
     query: string,
-    options: { includeDotDirectories: boolean; signal: AbortSignal }
+    options: { includeDotDirectories: boolean; includeIssueDetails?: boolean; signal: AbortSignal }
   ): Promise<DirectorySearchResult>;
 }
 
diff --git a/frontend/src/services/companionSettingsSync.ts b/frontend/src/services/companionSettingsSync.ts
index c80da385..93362f55 100644
--- a/frontend/src/services/companionSettingsSync.ts
+++ b/frontend/src/services/companionSettingsSync.ts
@@ -12,7 +12,7 @@ import api from "./api";
 import { isAuthRequired } from "./authConfig";
 import { authSession } from "./authSession";
 import { subscribeBackendRecoveryConfirmed } from "./backendRecoveryEvents";
-import companionService from "./companion";
+import companionService, { isCompanionAuthSignatureMismatch, isCompanionPairingMissing } from "./companion";
 import { companionSession } from "./companionSession";
 import { COMPANION_SETTINGS_CHANGED_EVENT } from "./companionSettingsEvents";
 
@@ -25,6 +25,7 @@ export type SettingsSyncPhase =
   | "synchronizing"
   | "update_required"
   | "authority_conflict"
+  | "pairing_required"
   | "delivery_failed";
 export interface SettingsSyncSnapshot {
   phase: SettingsSyncPhase;
@@ -278,19 +279,21 @@ class CompanionSettingsSynchronizer {
       const status = isApiError(error) ? error.response?.status : undefined;
       const code = isApiError(error) ? error.response?.data?.code : undefined;
       const phase =
-        status === 404 || status === 426 || code === "settings_update_required"
+        status === 404 || status === 426 || code === "settings_update_required" || code === "companion_browser_update_required"
           ? "update_required"
           : code === "settings_authority_conflict"
             ? "authority_conflict"
-            : "delivery_failed";
-      this.blocked = phase === "authority_conflict" || phase === "update_required";
+            : isCompanionAuthSignatureMismatch(error) || isCompanionPairingMissing(error)
+              ? "pairing_required"
+              : "delivery_failed";
+      this.blocked = phase === "authority_conflict" || phase === "update_required" || phase === "pairing_required";
       this.publish({
         ...this.snapshot,
         phase,
-        message: getApiErrorMessage(
-          error,
-          "Settings delivery failed. Check the connection and retry. The last valid settings remain active."
-        ),
+        message:
+          phase === "pairing_required"
+            ? null
+            : getApiErrorMessage(error, "Settings delivery failed. Check the connection and retry. The last valid settings remain active."),
         sections: Object.fromEntries(Object.keys(this.snapshot.sections).map((name) => [name, phase])),
       });
       delay = RETRY_DELAYS_MS[this.retries++] ?? CHECK_INTERVAL_MS;
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index 02eef95f..cf80b2be 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -609,17 +609,25 @@ export interface ScanProgress {
   started_at_ms: number;
 }
 
+export interface DirectoryIssueDetail {
+  path: string;
+  code: "access_denied" | "unsupported_encoding" | "unsafe_traversal" | "scan_failed";
+}
+
 export interface DirectorySearchResult {
   search_contract_version?: number | null;
   results: string[];
   match_ranks?: Record<string, number>;
   total_matches: number;
-  cache_state: "empty" | "building" | "ready" | "updating";
+  cache_state: "empty" | "opening" | "building" | "ready" | "updating";
   directory_count: number;
   matched_term_counts?: Record<string, number>;
   accepted_revision?: number | null;
   coverage?: "partial" | "complete" | "uncertain" | null;
   coverage_issue_count?: number;
+  issue_details_available?: boolean;
+  issue_details?: DirectoryIssueDetail[] | null;
+  issue_details_incomplete?: boolean;
   last_verified_at_ms?: number | null;
   status_message?: string | null;
   monitoring_state?: "starting" | "healthy" | "recovering" | "unavailable" | null;
diff --git a/website-meta/docs-reports/docs-structure-report.html b/website-meta/docs-reports/docs-structure-report.html
index 7d05afb2..922b319b 100644
--- a/website-meta/docs-reports/docs-structure-report.html
+++ b/website-meta/docs-reports/docs-structure-report.html
@@ -268,7 +268,7 @@ <h2 class="diff-modal__title" id="diff-modal-title">Content diff</h2>
     </div>
   </div>
 
-  <script id="report-data" type="application/json">{"meta": {"title": "Docs Structure Report", "current_version": "1.0", "report_output": "website-meta/docs-reports/docs-structure-report.html"}, "versions": [{"slug": "0.7", "label": "0.7", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "0.8", "label": "0.8", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "0.9", "label": "0.9", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "1.0", "label": "1.0", "status": "current", "visible": true, "searchable": true, "is_current": true}, {"slug": "2.0", "label": "2.0", "status": "preview", "visible": true, "searchable": false, "is_current": false}], "warnings": [], "rows": [{"id": "book:user-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "user-guide", "title": "User Guide", "path": "user-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 6, "diff_removed": 5}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"User Guide\"\n+++\n\nStart with [What Is Sambee?](./getting-started/what-is-sambee/) for the definition or [What Can You Do With Sambee?](./getting-started/what-can-you-do-with-sambee/) for practical benefits.\n\n- [Find and browse files](./find-and-browse-files/connect-to-an-smb-share/): Open a connection and reach a folder.\n- [Organize files](./organize-and-transfer-files/copy-and-move-files/): Copy or move selected items between locations.\n- [View and edit files](./view-and-edit-files/view-images-and-read-documents/): Preview designs and documents or edit Markdown.\n- [Use desktop apps and local drives](./use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/): Add optional Companion features.\n- [Get help](./troubleshooting/common-user-problems/): Recover from access, editing, or transfer problems.\n- [Check formats](./reference/supported-file-formats/): Find preview support and format limits.\n\nFor deployment and policy, use the [Admin Guide](../admin-guide/). For implementation, use the [Developer Guide](../developer-guide/).\n\n", "0.8": "+++\ntitle = \"User Guide\"\n+++\n\nStart with [What Is Sambee?](./getting-started/what-is-sambee/) for the definition or [What Can You Do With Sambee?](./getting-started/what-can-you-do-with-sambee/) for practical benefits.\n\n- [Find and browse files](./find-and-browse-files/connect-to-an-smb-share/): Open a connection and reach a folder.\n- [Organize files](./organize-and-transfer-files/copy-and-move-files/): Copy or move selected items between locations.\n- [View and edit files](./view-and-edit-files/view-images-and-read-documents/): Preview designs and documents or edit Markdown.\n- [Use desktop apps and local drives](./use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/): Add optional Companion features.\n- [Get help](./troubleshooting/common-user-problems/): Recover from access, editing, or transfer problems.\n- [Check formats](./reference/supported-file-formats/): Find preview support and format limits.\n\nFor deployment and policy, use the [Admin Guide](../admin-guide/). For implementation, use the [Developer Guide](../developer-guide/).\n\n", "0.9": "+++\ntitle = \"User Guide\"\n+++\n\nStart with [What Is Sambee?](./getting-started/what-is-sambee/) for the definition or [What Can You Do With Sambee?](./getting-started/what-can-you-do-with-sambee/) for practical benefits.\n\n- [Find and browse files](./find-and-browse-files/connect-to-an-smb-share/): Open a connection and reach a folder.\n- [Organize files](./organize-and-transfer-files/copy-and-move-files/): Copy or move selected items between locations.\n- [View and edit files](./view-and-edit-files/view-images-and-read-documents/): Preview designs and documents or edit Markdown.\n- [Use desktop apps and local drives](./use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/): Add optional Companion features.\n- [Get help](./troubleshooting/common-user-problems/): Recover from access, editing, or transfer problems.\n- [Check formats](./reference/supported-file-formats/): Find preview support and format limits.\n\nFor deployment and policy, use the [Admin Guide](../admin-guide/). For implementation, use the [Developer Guide](../developer-guide/).\n\n", "1.0": "+++\ntitle = \"User Guide\"\n+++\n\nStart with [What Is Sambee?](./getting-started/what-is-sambee/) for the definition or [What Can You Do With Sambee?](./getting-started/what-can-you-do-with-sambee/) for practical benefits.\n\n- [Find and browse files](./find-and-browse-files/connect-to-an-smb-share/): Open a connection, select items, and find recent locations.\n- [Organize and transfer files](./organize-and-transfer-files/copy-and-move-files/): Copy, move, upload, or download files.\n- [Inspect ZIP archives](./organize-and-transfer-files/work-with-zip-archives/): Preview contents without extracting the whole archive.\n- [View and edit files](./view-and-edit-files/view-images-and-read-documents/): Preview designs, edit text, or update Markdown tables.\n- [Use desktop apps and local drives](./use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/): Add optional Companion features.\n- [Manage your account and preferences](./account-and-preferences/manage-your-account/): Control sessions and personal history.\n- [Get help](./troubleshooting/common-user-problems/): Recover from access, saving, sharing, or transfer problems.\n- [Check formats](./reference/supported-file-formats/): Find preview support and format limits.\n\nFor deployment and policy, use the [Admin Guide](../admin-guide/). For implementation, use the [Developer Guide](../developer-guide/).\n", "2.0": "+++\ntitle = \"User Guide\"\n+++\n\nStart with [What Is Sambee?](./getting-started/what-is-sambee/) for the definition or [What Can You Do With Sambee?](./getting-started/what-can-you-do-with-sambee/) for practical benefits.\n\n- [Find and browse files](./find-and-browse-files/connect-to-an-smb-share/): Open a connection, select items, and find recent locations.\n- [Organize and transfer files](./organize-and-transfer-files/copy-and-move-files/): Copy, move, upload, or download files.\n- [Inspect ZIP archives](./organize-and-transfer-files/work-with-zip-archives/): Preview contents without extracting the whole archive.\n- [View and edit files](./view-and-edit-files/view-images-and-read-documents/): Preview designs, edit text, or update Markdown tables.\n- [Use desktop apps and local drives](./use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/): Add optional Companion features.\n- [Manage your account and preferences](./account-and-preferences/manage-your-account/): Control sessions and personal history.\n- [Get help](./troubleshooting/common-user-problems/): Recover from access, saving, sharing, or transfer problems.\n- [Check formats](./reference/supported-file-formats/): Find preview support and format limits.\n\nFor deployment and policy, use the [Admin Guide](../admin-guide/). For implementation, use the [Developer Guide](../developer-guide/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/getting-started", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "getting-started", "title": "Getting Started", "path": "user-guide/getting-started", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/getting-started/what-is-sambee", "parent_id": "section:user-guide/getting-started", "depth": 2, "kind": "page", "label": "what-is-sambee", "title": "What Is Sambee", "path": "user-guide/getting-started/what-is-sambee", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 1}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "branched", "source_version": "0.8", "diff_added": 27, "diff_removed": 11}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "0.8": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit text and Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\nEdit supported text files directly in storage, or change Markdown tables in their rendered view without aligning markup. See [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/) and [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "0.9": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit text and Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\nEdit supported text files directly in storage, or change Markdown tables in their rendered view without aligning markup. See [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/) and [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "1.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee is a browser-based workspace for files on SMB shares and local drives. Access your data from PCs, phones, and tablets. View images, read PDFs, and edit Markdown right in your browser. On the desktop, open any file in the natively installed apps you already use. Sambee saves your changes back to the original location.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSambee provides access to two types of storage: SMB file shares and your computer's local drives. You can move and copy files between them without restrictions, e.g. from your PC's local drive to a file share, or between different SMB shares.\n\nLocal drive access is requires Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nAny kind of text file can be viewed and edited in the built-in text editor. It provides syntax highlighting for many file types, offers search \u0026 replace, and opens even very large files.\n\n### Desktop App Integration\n\nSambee bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container. See [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/).\n", "2.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee is a browser-based workspace for files on SMB shares and local drives. Access your data from PCs, phones, and tablets. View images, read PDFs, and edit Markdown right in your browser. On the desktop, open any file in the natively installed apps you already use. Sambee saves your changes back to the original location.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSambee provides access to two types of storage: SMB file shares and your computer's local drives. You can move and copy files between them without restrictions, e.g. from your PC's local drive to a file share, or between different SMB shares.\n\nLocal drive access is requires Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nAny kind of text file can be viewed and edited in the built-in text editor. It provides syntax highlighting for many file types, offers search \u0026 replace, and opens even very large files.\n\n### Desktop App Integration\n\nSambee bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container. See [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "0.8": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit text and Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\nEdit supported text files directly in storage, or change Markdown tables in their rendered view without aligning markup. See [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/) and [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "0.9": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit text and Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\nEdit supported text files directly in storage, or change Markdown tables in their rendered view without aligning markup. See [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/) and [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "1.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee is a browser-based workspace for files on SMB shares and local drives. Access your data from PCs, phones, and tablets. View images, read PDFs, and edit Markdown right in your browser. On the desktop, open any file in the natively installed apps you already use. Sambee saves your changes back to the original location.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSambee provides access to two types of storage: SMB file shares and your computer's local drives. You can move and copy files between them without restrictions, e.g. from your PC's local drive to a file share, or between different SMB shares.\n\nLocal drive access is requires Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nAny kind of text file can be viewed and edited in the built-in text editor. It provides syntax highlighting for many file types, offers search \u0026 replace, and opens even very large files.\n\n### Desktop App Integration\n\nSambee bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container. See [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/).\n", "2.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee is a browser-based workspace for files on SMB shares and local drives. Access your data from PCs, phones, and tablets. View images, read PDFs, and edit Markdown right in your browser. On the desktop, open any file in the natively installed apps you already use. Sambee saves your changes back to the original location.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSambee provides access to two types of storage: SMB file shares and your computer's local drives. You can move and copy files between them without restrictions, e.g. from your PC's local drive to a file share, or between different SMB shares.\n\nLocal drive access is requires Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nAny kind of text file can be viewed and edited in the built-in text editor. It provides syntax highlighting for many file types, offers search \u0026 replace, and opens even very large files.\n\n### Desktop App Integration\n\nSambee bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container. See [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/getting-started/what-can-you-do-with-sambee", "parent_id": "section:user-guide/getting-started", "depth": 2, "kind": "page", "label": "what-can-you-do-with-sambee", "title": "What Can You Do With Sambee", "path": "user-guide/getting-started/what-can-you-do-with-sambee", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 1}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "branched", "source_version": "0.8", "diff_added": 13, "diff_removed": 13}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Review a design from your phone or open a network file in your favorite desktop app. Sambee brings these workflows to the storage you already use.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "0.8": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Preview design files from your phone, change a Markdown table without editing its markup, or open a network file in your favorite desktop app.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Change Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in its rendered table view, instead of aligning pipes and rows in source text. Your document stays a Markdown file in its existing storage. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "0.9": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Preview design files from your phone, change a Markdown table without editing its markup, or open a network file in your favorite desktop app.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Change Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in its rendered table view, instead of aligning pipes and rows in source text. Your document stays a Markdown file in its existing storage. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "1.0": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nWork more easily with your files on the storage you already have. Preview image files on your phone, browse a ZIP without unpacking it, edit a Markdown table effortlessly, or open a network file in your favorite desktop app. Sambee brings all of this to the storage you already have.\n\n## Give Your Existing Storage a Modern Workspace\n\nYour project files can stay on your NAS or Windows file server. There's no cloud to migrate to and no synced copy to maintain. Just [connect to an SMB share](../../find-and-browse-files/connect-to-an-smb-share/) and start working. Add Companion to [bring local drives into the same workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files on Your Phone\n\nCheck a Photoshop design or a HEIC photo straight from a network share. You don't need the desktop app, and you don't need to download the file first. Swipe through large image collections, including formats your browser can't display natively. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/), [Supported File Formats](../../reference/supported-file-formats/), and [Mobile Navigation](../../find-and-browse-files/mobile-navigation/).\n\n## Look Inside a ZIP Without Unpacking It\n\nOpen a ZIP like a folder and view the images and documents inside. Find what you need without extracting the whole archive, then download or extract only the files you want. This works even with read-only access to an SMB share, and you don't need Companion. See [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/).\n\n## Edit Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in a rendered table view instead of lining up pipes in source text. The document stays a plain Markdown file, right where it was. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a folder name and jump straight to it. [Get back to recent files and locations](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) in a few keystrokes. On desktop, use [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders side by side or [move files between them](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Edit in Your Desktop Apps, Save Back to the Share\n\nOpen network files in Word, Photoshop, LibreOffice, or any other installed app. Sambee Companion handles the handoff and uploads your changes back to the original location, so you don't have to juggle downloads and uploads yourself. See [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "2.0": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nWork more easily with your files on the storage you already have. Preview image files on your phone, browse a ZIP without unpacking it, edit a Markdown table effortlessly, or open a network file in your favorite desktop app. Sambee brings all of this to the storage you already have.\n\n## Give Your Existing Storage a Modern Workspace\n\nYour project files can stay on your NAS or Windows file server. There's no cloud to migrate to and no synced copy to maintain. Just [connect to an SMB share](../../find-and-browse-files/connect-to-an-smb-share/) and start working. Add Companion to [bring local drives into the same workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files on Your Phone\n\nCheck a Photoshop design or a HEIC photo straight from a network share. You don't need the desktop app, and you don't need to download the file first. Swipe through large image collections, including formats your browser can't display natively. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/), [Supported File Formats](../../reference/supported-file-formats/), and [Mobile Navigation](../../find-and-browse-files/mobile-navigation/).\n\n## Look Inside a ZIP Without Unpacking It\n\nOpen a ZIP like a folder and view the images and documents inside. Find what you need without extracting the whole archive, then download or extract only the files you want. This works even with read-only access to an SMB share, and you don't need Companion. See [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/).\n\n## Edit Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in a rendered table view instead of lining up pipes in source text. The document stays a plain Markdown file, right where it was. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a folder name and jump straight to it. [Get back to recent files and locations](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) in a few keystrokes. On desktop, use [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders side by side or [move files between them](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Edit in Your Desktop Apps, Save Back to the Share\n\nOpen network files in Word, Photoshop, LibreOffice, or any other installed app. Sambee Companion handles the handoff and uploads your changes back to the original location, so you don't have to juggle downloads and uploads yourself. See [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Review a design from your phone or open a network file in your favorite desktop app. Sambee brings these workflows to the storage you already use.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "0.8": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Preview design files from your phone, change a Markdown table without editing its markup, or open a network file in your favorite desktop app.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Change Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in its rendered table view, instead of aligning pipes and rows in source text. Your document stays a Markdown file in its existing storage. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "0.9": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Preview design files from your phone, change a Markdown table without editing its markup, or open a network file in your favorite desktop app.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Change Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in its rendered table view, instead of aligning pipes and rows in source text. Your document stays a Markdown file in its existing storage. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "1.0": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nWork more easily with your files on the storage you already have. Preview image files on your phone, browse a ZIP without unpacking it, edit a Markdown table effortlessly, or open a network file in your favorite desktop app. Sambee brings all of this to the storage you already have.\n\n## Give Your Existing Storage a Modern Workspace\n\nYour project files can stay on your NAS or Windows file server. There's no cloud to migrate to and no synced copy to maintain. Just [connect to an SMB share](../../find-and-browse-files/connect-to-an-smb-share/) and start working. Add Companion to [bring local drives into the same workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files on Your Phone\n\nCheck a Photoshop design or a HEIC photo straight from a network share. You don't need the desktop app, and you don't need to download the file first. Swipe through large image collections, including formats your browser can't display natively. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/), [Supported File Formats](../../reference/supported-file-formats/), and [Mobile Navigation](../../find-and-browse-files/mobile-navigation/).\n\n## Look Inside a ZIP Without Unpacking It\n\nOpen a ZIP like a folder and view the images and documents inside. Find what you need without extracting the whole archive, then download or extract only the files you want. This works even with read-only access to an SMB share, and you don't need Companion. See [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/).\n\n## Edit Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in a rendered table view instead of lining up pipes in source text. The document stays a plain Markdown file, right where it was. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a folder name and jump straight to it. [Get back to recent files and locations](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) in a few keystrokes. On desktop, use [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders side by side or [move files between them](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Edit in Your Desktop Apps, Save Back to the Share\n\nOpen network files in Word, Photoshop, LibreOffice, or any other installed app. Sambee Companion handles the handoff and uploads your changes back to the original location, so you don't have to juggle downloads and uploads yourself. See [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "2.0": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nWork more easily with your files on the storage you already have. Preview image files on your phone, browse a ZIP without unpacking it, edit a Markdown table effortlessly, or open a network file in your favorite desktop app. Sambee brings all of this to the storage you already have.\n\n## Give Your Existing Storage a Modern Workspace\n\nYour project files can stay on your NAS or Windows file server. There's no cloud to migrate to and no synced copy to maintain. Just [connect to an SMB share](../../find-and-browse-files/connect-to-an-smb-share/) and start working. Add Companion to [bring local drives into the same workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files on Your Phone\n\nCheck a Photoshop design or a HEIC photo straight from a network share. You don't need the desktop app, and you don't need to download the file first. Swipe through large image collections, including formats your browser can't display natively. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/), [Supported File Formats](../../reference/supported-file-formats/), and [Mobile Navigation](../../find-and-browse-files/mobile-navigation/).\n\n## Look Inside a ZIP Without Unpacking It\n\nOpen a ZIP like a folder and view the images and documents inside. Find what you need without extracting the whole archive, then download or extract only the files you want. This works even with read-only access to an SMB share, and you don't need Companion. See [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/).\n\n## Edit Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in a rendered table view instead of lining up pipes in source text. The document stays a plain Markdown file, right where it was. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a folder name and jump straight to it. [Get back to recent files and locations](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) in a few keystrokes. On desktop, use [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders side by side or [move files between them](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Edit in Your Desktop Apps, Save Back to the Share\n\nOpen network files in Word, Photoshop, LibreOffice, or any other installed app. Sambee Companion handles the handoff and uploads your changes back to the original location, so you don't have to juggle downloads and uploads yourself. See [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/find-and-browse-files", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "find-and-browse-files", "title": "Find and Browse Files", "path": "user-guide/find-and-browse-files", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/connect-to-an-smb-share", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "connect-to-an-smb-share", "title": "Connect To An Smb Share", "path": "user-guide/find-and-browse-files/connect-to-an-smb-share", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "0.8": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "0.9": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "1.0": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "2.0": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "0.8": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "0.9": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "1.0": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "2.0": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/select-files-and-folders", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "select-files-and-folders", "title": "Select Files And Folders", "path": "user-guide/find-and-browse-files/select-files-and-folders", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 12, "diff_removed": 2}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 9, "diff_removed": 5}}, "content_versions": {"0.7": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "0.8": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "0.9": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "1.0": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Each pane has its own selection; bulk actions use the active pane.\n\n## Touch Selection\n\nOn phones, select an item from **More actions** or touch and hold its row. Tap more rows to change the selection, then use the pane's bottom selection controls.\n\nLarger touch devices can use the same behavior without switching to the phone layout. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#file-selection).\n\n## Keyboard Selection\n\n**Space** or **Insert** toggles selection on the focused row and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) rather than a second shortcut list here.\n\nContinue with [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) or [Download and Upload Files](../../organize-and-transfer-files/download-and-upload-files/).\n", "2.0": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Each pane keeps its selection when you switch panes; bulk actions use the active pane.\n\n## Desktop Mouse Selection\n\nWith touch selection off, click the name to open an item or its icon to select it. After the first selection, icons become selection controls. **Shift**-click an icon to add a range without losing earlier selections. Mouse and keyboard selection share the range anchor.\n\nClicking outside the icon or in empty list space clears selection **without opening the item**; click again to open it. **Escape** also clears selection. Sorting or starting File Search clears the active pane's selection.\n\n## Touch Selection\n\nOn phones, select from **More actions** or touch and hold a row. Tap additional rows to change the selection, then use the pane's bottom selection controls. Larger touch devices can use this behavior too; see [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#file-selection).\n\n## Keyboard Selection\n\nSee [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for the selection commands.\n\nContinue with [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) or [Download and Upload Files](../../organize-and-transfer-files/download-and-upload-files/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "0.8": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "0.9": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "1.0": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Each pane has its own selection; bulk actions use the active pane.\n\n## Touch Selection\n\nOn phones, select an item from **More actions** or touch and hold its row. Tap more rows to change the selection, then use the pane's bottom selection controls.\n\nLarger touch devices can use the same behavior without switching to the phone layout. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#file-selection).\n\n## Keyboard Selection\n\n**Space** or **Insert** toggles selection on the focused row and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) rather than a second shortcut list here.\n\nContinue with [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) or [Download and Upload Files](../../organize-and-transfer-files/download-and-upload-files/).\n", "2.0": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Each pane keeps its selection when you switch panes; bulk actions use the active pane.\n\n## Desktop Mouse Selection\n\nWith touch selection off, click the name to open an item or its icon to select it. After the first selection, icons become selection controls. **Shift**-click an icon to add a range without losing earlier selections. Mouse and keyboard selection share the range anchor.\n\nClicking outside the icon or in empty list space clears selection **without opening the item**; click again to open it. **Escape** also clears selection. Sorting or starting File Search clears the active pane's selection.\n\n## Touch Selection\n\nOn phones, select from **More actions** or touch and hold a row. Tap additional rows to change the selection, then use the pane's bottom selection controls. Larger touch devices can use this behavior too; see [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#file-selection).\n\n## Keyboard Selection\n\nSee [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for the selection commands.\n\nContinue with [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) or [Download and Upload Files](../../organize-and-transfer-files/download-and-upload-files/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "smart-navigation-and-the-quick-bar", "title": "Smart Navigation And The Quick Bar", "path": "user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 44, "diff_removed": 8}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 16, "diff_removed": 12}}, "content_versions": {"0.7": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "0.8": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "0.9": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "1.0": "+++\ntitle = \"Find Files and Return to Recent Locations\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nHistory is private to your account. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#clear-personal-history) to clear it.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search searches names in the active directory's loaded files and your recent-file history. It is not a global file index and does not search contents. A file in both groups appears once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\n## Locate and Run Any Command\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/).\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n", "2.0": "+++\ntitle = \"Find Files and Return to Recent Locations\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\nPress \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to search directory paths across the current connection and your recent locations. For example, `annual reports` finds paths containing either term, with matches for both terms ranked first.\n\nResults can be incomplete while Sambee scans folders. During a scan, the status shows directories found or directories checked. An interrupted scan keeps committed progress for its next attempt. If a folder is missing from search, browse to it directly.\n\nIf directory search is temporarily unavailable, the quick bar keeps recent history and results already shown for the same search. It checks for recovery while open. A paused status does not mean that a scan is still running. Restore source access if the message reports a connection problem; direct browsing can remain available while search recovers.\n\nDirectory indexes are reused after a restart. Results can remain unverified while background checks run. Missing removable media keeps its saved index; insert or mount the volume again to resume search. SMB search includes ordinary folders inside the configured share and folder, including server-mounted storage. Local search does not cross into other mounts. Redirects and reparse points are excluded.\n\n### Recent Directory History\n\nWith an empty search box, Recent directories shows your saved locations across connections. These remain available while directory search loads.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nHistory is private to your account. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#clear-personal-history) to clear it.\n\n### Missing or Inaccessible Folders\n\nIf a folder cannot be opened, Sambee keeps your current location. If the open folder or a directly linked folder no longer exists, Sambee tries an accessible parent instead. Follow the displayed recovery action if access fails.\n\nConfirmed missing folders are removed from recent history. Temporary connection or permission problems keep the history entry for another attempt.\n\n## Find Files with File Search\n\nPress \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus to search loaded filenames in the active directory and your recent-file history. It does not search all files or file contents. Files matching more search terms rank first.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nConfirmed missing files are removed from recent history. Temporary access problems keep the entry for another attempt. If a native application does not open the file, check Companion or the application for an error.\n\n## Locate and Run Any Command\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/).\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "0.8": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "0.9": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "1.0": "+++\ntitle = \"Find Files and Return to Recent Locations\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nHistory is private to your account. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#clear-personal-history) to clear it.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search searches names in the active directory's loaded files and your recent-file history. It is not a global file index and does not search contents. A file in both groups appears once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\n## Locate and Run Any Command\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/).\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n", "2.0": "+++\ntitle = \"Find Files and Return to Recent Locations\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\nPress \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to search directory paths across the current connection and your recent locations. For example, `annual reports` finds paths containing either term, with matches for both terms ranked first.\n\nResults can be incomplete while Sambee scans folders. During a scan, the status shows directories found or directories checked. An interrupted scan keeps committed progress for its next attempt. If a folder is missing from search, browse to it directly.\n\nIf directory search is temporarily unavailable, the quick bar keeps recent history and results already shown for the same search. It checks for recovery while open. A paused status does not mean that a scan is still running. Restore source access if the message reports a connection problem; direct browsing can remain available while search recovers.\n\nDirectory indexes are reused after a restart. Results can remain unverified while background checks run. Missing removable media keeps its saved index; insert or mount the volume again to resume search. SMB search includes ordinary folders inside the configured share and folder, including server-mounted storage. Local search does not cross into other mounts. Redirects and reparse points are excluded.\n\n### Recent Directory History\n\nWith an empty search box, Recent directories shows your saved locations across connections. These remain available while directory search loads.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nHistory is private to your account. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#clear-personal-history) to clear it.\n\n### Missing or Inaccessible Folders\n\nIf a folder cannot be opened, Sambee keeps your current location. If the open folder or a directly linked folder no longer exists, Sambee tries an accessible parent instead. Follow the displayed recovery action if access fails.\n\nConfirmed missing folders are removed from recent history. Temporary connection or permission problems keep the history entry for another attempt.\n\n## Find Files with File Search\n\nPress \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus to search loaded filenames in the active directory and your recent-file history. It does not search all files or file contents. Files matching more search terms rank first.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nConfirmed missing files are removed from recent history. Temporary access problems keep the entry for another attempt. If a native application does not open the file, check Companion or the application for an error.\n\n## Locate and Run Any Command\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/).\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/mobile-navigation", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "mobile-navigation", "title": "Mobile Navigation", "path": "user-guide/find-and-browse-files/mobile-navigation", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "0.8": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "0.9": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "1.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "2.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor sharing stored files, viewer copies, and unsaved text, see [Share Files on Phones and Tablets](../../organize-and-transfer-files/share-files-on-phones-and-tablets/).\n\nWith unsaved edits, navigation offers **Save**, **Discard**, or **Cancel**. Cancel keeps the draft and current location; a failed Save keeps the editor open. Browser history does not undo saved changes or restore discarded edits. See [Recover Unsaved Edits](../../view-and-edit-files/recover-unsaved-edits/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "0.8": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "0.9": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "1.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "2.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor sharing stored files, viewer copies, and unsaved text, see [Share Files on Phones and Tablets](../../organize-and-transfer-files/share-files-on-phones-and-tablets/).\n\nWith unsaved edits, navigation offers **Save**, **Discard**, or **Cancel**. Cancel keeps the draft and current location; a failed Save keeps the editor open. Browser history does not undo saved changes or restore discarded edits. See [Recover Unsaved Edits](../../view-and-edit-files/recover-unsaved-edits/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/dual-pane-mode", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "dual-pane-mode", "title": "Dual Pane Mode", "path": "user-guide/find-and-browse-files/dual-pane-mode", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 1, "diff_removed": 1}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 13, "diff_removed": 4}}, "content_versions": {"0.7": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.8": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.9": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "1.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers, or [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/) for extraction.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "2.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nUse \u003ckbd\u003eTab\u003c/kbd\u003e to move focus between the panes. To focus a specific pane, use **Focus Left Pane** or **Focus Right Pane** in command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e). **Focus Right Pane** also opens dual-pane mode if only one pane is visible.\n\n## Match Pane Locations\n\nUse these commands to show the same connection and directory in both panes:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eLeft\u003c/kbd\u003e to set the left pane to the right pane's location.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eRight\u003c/kbd\u003e to set the right pane to the left pane's location.\n\nThe direction selects the pane to change, regardless of which pane is active. The active pane and keyboard focus stay unchanged. These commands copy only the location, including archive subdirectories. They don't copy or move files, selections, or pane preferences. Both locations must finish loading first. If they already match, nothing changes. Use browser Back to restore the previous locations.\n\nTo open the active pane's location separately, press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e. The new tab contains one pane. The original tab stays unchanged.\n\nAll three commands are also available through command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e).\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers, or [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/) for extraction.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.8": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.9": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "1.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers, or [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/) for extraction.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "2.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nUse \u003ckbd\u003eTab\u003c/kbd\u003e to move focus between the panes. To focus a specific pane, use **Focus Left Pane** or **Focus Right Pane** in command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e). **Focus Right Pane** also opens dual-pane mode if only one pane is visible.\n\n## Match Pane Locations\n\nUse these commands to show the same connection and directory in both panes:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eLeft\u003c/kbd\u003e to set the left pane to the right pane's location.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eRight\u003c/kbd\u003e to set the right pane to the left pane's location.\n\nThe direction selects the pane to change, regardless of which pane is active. The active pane and keyboard focus stay unchanged. These commands copy only the location, including archive subdirectories. They don't copy or move files, selections, or pane preferences. Both locations must finish loading first. If they already match, nothing changes. Use browser Back to restore the previous locations.\n\nTo open the active pane's location separately, press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e. The new tab contains one pane. The original tab stays unchanged.\n\nAll three commands are also available through command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e).\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers, or [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/) for extraction.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/keyboard-navigation-and-shortcuts", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "keyboard-navigation-and-shortcuts", "title": "Keyboard Navigation And Shortcuts", "path": "user-guide/find-and-browse-files/keyboard-navigation-and-shortcuts", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 37, "diff_removed": 13}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 8, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.8": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.9": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "1.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee. Press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e for a searchable list of shortcuts in the app.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "2.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee. Press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e for a searchable list of shortcuts in the app.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Open the active pane's current location in a new browser tab |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eLeft\u003c/kbd\u003e | Set the left pane to the right pane's connection and directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eRight\u003c/kbd\u003e | Set the right pane to the left pane's connection and directory |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\nThe location commands are also available through command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e). They require loaded pane locations and are unavailable in viewers, dialogs, and text inputs. Opening a new tab copies only the location, including an archive subdirectory, not selection, scroll position, or the second pane. Browser settings control where the page opens. If your operating system uses \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e for a terminal, use command search instead.\n\nMatching pane locations doesn't move files or change the active pane. Use browser Back to restore the previous locations. If both locations already match, the command makes no change.\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Retry editing when the file is read-only because its lock or write access is temporarily unavailable; disabled while a retry is pending |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.8": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.9": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "1.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee. Press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e for a searchable list of shortcuts in the app.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "2.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee. Press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e for a searchable list of shortcuts in the app.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Open the active pane's current location in a new browser tab |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eLeft\u003c/kbd\u003e | Set the left pane to the right pane's connection and directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eRight\u003c/kbd\u003e | Set the right pane to the left pane's connection and directory |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\nThe location commands are also available through command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e). They require loaded pane locations and are unavailable in viewers, dialogs, and text inputs. Opening a new tab copies only the location, including an archive subdirectory, not selection, scroll position, or the second pane. Browser settings control where the page opens. If your operating system uses \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e for a terminal, use command search instead.\n\nMatching pane locations doesn't move files or change the active pane. Use browser Back to restore the previous locations. If both locations already match, the command makes no change.\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Retry editing when the file is read-only because its lock or write access is temporarily unavailable; disabled while a retry is pending |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/organize-and-transfer-files", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "organize-and-transfer-files", "title": "Organize and Transfer Files", "path": "user-guide/organize-and-transfer-files", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/organize-and-transfer-files/copy-and-move-files", "parent_id": "section:user-guide/organize-and-transfer-files", "depth": 2, "kind": "page", "label": "copy-and-move-files", "title": "Copy And Move Files", "path": "user-guide/organize-and-transfer-files/copy-and-move-files", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 5}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 14, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "0.8": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "0.9": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "1.0": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop. Select source files or folders in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move. Transfers work between SMB connections, local drives, and shares and drives. The destination must be writable; local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/). Sambee completes the destination copy before removing the source during a move.\n\nIf a destination item exists, use **Target already exists** to skip it or choose a different name. To extract ZIP members instead, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Partial Moves and Cancellation\n\nIf Sambee creates the destination but cannot remove the original, it reports a partial move and keeps the original. Cancellation or failure does not undo earlier completed items. Review both locations before retrying or deleting a retained source. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "2.0": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop. Select source files or folders in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move. Transfers work between SMB connections, local drives, and shares and drives. The destination must be writable; local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/). Sambee completes the destination copy before removing the source during a move. For ZIP members, use [extraction](../work-with-zip-archives/#extract-selected-members); members cannot be moved.\n\n## Existing Destination Items\n\nIn **Target already exists**, skip, overwrite, overwrite only if the source is newer, or choose another name. You can apply a choice to remaining conflicts. Same-name directories are merged without deleting destination-only entries. A file cannot replace a directory or the reverse.\n\n## Partial Moves and Cancellation\n\nFor moves between SMB connections, the destination file is complete before source deletion. An authorized overwrite does not first delete the visible destination. Another writer can prevent a move from starting.\n\n- Cancellation before destination publication leaves both locations unchanged for that file.\n- Cancellation after publication but before source deletion retains the destination and reports the retained source.\n- Rejected source deletion retains the confirmed destination and reports the retained source.\n- If deletion or final close cannot be confirmed, Sambee reports uncertainty. Cancellation after deletion starts does not guarantee that the source remains.\n\nDirectories can be partially moved. Earlier completed files and replacements are not rolled back. An uncertain item stops the remaining batch; a retained-source warning can allow later items to continue. Each selected directory uses the destination parent captured when the confirmation opened.\n\nInspect both locations before retrying. Do not assume an uncertain source was retained. The completed dialog offers **Close**, not a repeat of the batch. If source validation fails after a copy was published, the destination remains and the failure is reported. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "0.8": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "0.9": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "1.0": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop. Select source files or folders in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move. Transfers work between SMB connections, local drives, and shares and drives. The destination must be writable; local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/). Sambee completes the destination copy before removing the source during a move.\n\nIf a destination item exists, use **Target already exists** to skip it or choose a different name. To extract ZIP members instead, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Partial Moves and Cancellation\n\nIf Sambee creates the destination but cannot remove the original, it reports a partial move and keeps the original. Cancellation or failure does not undo earlier completed items. Review both locations before retrying or deleting a retained source. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "2.0": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop. Select source files or folders in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move. Transfers work between SMB connections, local drives, and shares and drives. The destination must be writable; local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/). Sambee completes the destination copy before removing the source during a move. For ZIP members, use [extraction](../work-with-zip-archives/#extract-selected-members); members cannot be moved.\n\n## Existing Destination Items\n\nIn **Target already exists**, skip, overwrite, overwrite only if the source is newer, or choose another name. You can apply a choice to remaining conflicts. Same-name directories are merged without deleting destination-only entries. A file cannot replace a directory or the reverse.\n\n## Partial Moves and Cancellation\n\nFor moves between SMB connections, the destination file is complete before source deletion. An authorized overwrite does not first delete the visible destination. Another writer can prevent a move from starting.\n\n- Cancellation before destination publication leaves both locations unchanged for that file.\n- Cancellation after publication but before source deletion retains the destination and reports the retained source.\n- Rejected source deletion retains the confirmed destination and reports the retained source.\n- If deletion or final close cannot be confirmed, Sambee reports uncertainty. Cancellation after deletion starts does not guarantee that the source remains.\n\nDirectories can be partially moved. Earlier completed files and replacements are not rolled back. An uncertain item stops the remaining batch; a retained-source warning can allow later items to continue. Each selected directory uses the destination parent captured when the confirmation opened.\n\nInspect both locations before retrying. Do not assume an uncertain source was retained. The completed dialog offers **Close**, not a repeat of the batch. If source validation fails after a copy was published, the destination remains and the failure is reported. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/organize-and-transfer-files/share-files-and-links", "parent_id": "section:user-guide/organize-and-transfer-files", "depth": 2, "kind": "page", "label": "share-files-and-links", "title": "Share Files And Links", "path": "user-guide/organize-and-transfer-files/share-files-and-links", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "missing"}}, "content_versions": {"0.7": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "0.8": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "0.9": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "1.0": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "0.8": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "0.9": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "1.0": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/organize-and-transfer-files/download-and-upload-files", "parent_id": "section:user-guide/organize-and-transfer-files", "depth": 2, "kind": "page", "label": "download-and-upload-files", "title": "Download And Upload Files", "path": "user-guide/organize-and-transfer-files/download-and-upload-files", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"1.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nFor persistent archive creation and extraction, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If Sambee cannot confirm whether a folder upload succeeded, Sambee stops the remaining transfers; inspect the destination before trying again.\n\nSee [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer) before retrying a partial or uncertain upload.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n", "2.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nFor persistent archive creation and extraction, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If Sambee cannot confirm whether a folder upload succeeded, Sambee stops the remaining transfers; inspect the destination before trying again.\n\nSee [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer) before retrying a partial or uncertain upload.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n"}, "page_contents": {"1.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nFor persistent archive creation and extraction, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If Sambee cannot confirm whether a folder upload succeeded, Sambee stops the remaining transfers; inspect the destination before trying again.\n\nSee [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer) before retrying a partial or uncertain upload.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n", "2.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nFor persistent archive creation and extraction, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If Sambee cannot confirm whether a folder upload succeeded, Sambee stops the remaining transfers; inspect the destination before trying again.\n\nSee [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer) before retrying a partial or uncertain upload.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/organize-and-transfer-files/work-with-zip-archives", "parent_id": "section:user-guide/organize-and-transfer-files", "depth": 2, "kind": "page", "label": "work-with-zip-archives", "title": "Work With Zip Archives", "path": "user-guide/organize-and-transfer-files/work-with-zip-archives", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"1.0": "+++\ntitle = \"Work with ZIP Archives\"\n+++\n\n## Look Inside a ZIP\n\nOpen a ZIP as a virtual folder on an SMB share or paired local drive. Browse its directories and preview supported files inside it without extracting the whole archive. Read-only access is enough for inspection. Local archives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/); SMB archives do not.\n\nSambee cannot preview or extract encrypted members or members with unsupported compression. These members appear in lighter text; hover over a row to see its reason. Use another archive tool, with the password for encrypted members, to access them.\n\n## Download Selected Contents\n\nSelect archive members or folders and choose **Download** to get a new ZIP containing those items. A selected folder includes its contents. This does not create an archive in storage. See [download limits](../download-and-upload-files/#download-limits).\n\n## Extract Selected Members\n\nOn desktop, open the ZIP in the active pane and a writable physical folder in the other pane. Select members and press **F5** to extract them there. Selected directories include all their contents and empty directories. Archive members cannot be moved; **F6** is unavailable and does not modify the ZIP.\n\nExtraction continues for readable members inside a selected folder. The completion notice reports skipped members and gives separate counts for encryption and unsupported compression.\n\nExtraction can leave partial results after failure or cancellation. Inspect the destination before retrying; see [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n\n## Create an Archive in Storage\n\nUnlike a generated download, **Create archive** writes a persistent ZIP into the destination folder. For files selected inside a ZIP, open a writable physical folder on the **same SMB connection** in the other pane, then choose **Create archive**. Creating an archive from ZIP members is not available for local-drive or mixed-connection destinations.\n\nFor ordinary stored files or folders, select the source items and choose **Create archive** with a writable physical destination. Source items must belong to one connection. The action is unavailable for unsupported source or destination combinations; a ZIP virtual folder cannot be the destination.\n\nCancellation or failure can leave partial results. Inspect the destination and the final operation status before retrying.\n", "2.0": "+++\ntitle = \"Work with ZIP Archives\"\n+++\n\n## Look Inside a ZIP\n\nOpen a ZIP as a virtual folder on an SMB share or paired local drive. Browse its directories and preview supported files inside it without extracting the whole archive. Read-only access is enough for inspection. Local archives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/); SMB archives do not.\n\nSambee cannot preview or extract encrypted members or members with unsupported compression. These members appear in lighter text; hover over a row to see its reason. Use another archive tool, with the password for encrypted members, to access them.\n\n## Download Selected Contents\n\nSelect archive members or folders and choose **Download** to get a new ZIP containing those items. A selected folder includes its contents. This does not create an archive in storage. See [download limits](../download-and-upload-files/#download-limits).\n\n## Extract Selected Members\n\nOn desktop, open the ZIP in the active pane and a writable physical folder in the other pane. Select members and press **F5** to extract them there. Selected directories include all their contents and empty directories. Archive members cannot be moved; **F6** is unavailable and does not modify the ZIP.\n\nExtraction continues for readable members inside a selected folder. The completion notice reports skipped members and gives separate counts for encryption and unsupported compression.\n\nExtraction can leave partial results after failure or cancellation. Inspect the destination before retrying; see [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n\n## Create an Archive in Storage\n\nUnlike a generated download, **Create archive** writes a persistent ZIP into the destination folder. For files selected inside a ZIP, open a writable physical folder on the **same SMB connection** in the other pane, then choose **Create archive**. Creating an archive from ZIP members is not available for local-drive or mixed-connection destinations.\n\nFor ordinary stored files or folders, select the source items and choose **Create archive** with a writable physical destination. Source items must belong to one connection. The action is unavailable for unsupported source or destination combinations; a ZIP virtual folder cannot be the destination.\n\nCancellation or failure can leave partial results. Inspect the destination and the final operation status before retrying.\n"}, "page_contents": {"1.0": "+++\ntitle = \"Work with ZIP Archives\"\n+++\n\n## Look Inside a ZIP\n\nOpen a ZIP as a virtual folder on an SMB share or paired local drive. Browse its directories and preview supported files inside it without extracting the whole archive. Read-only access is enough for inspection. Local archives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/); SMB archives do not.\n\nSambee cannot preview or extract encrypted members or members with unsupported compression. These members appear in lighter text; hover over a row to see its reason. Use another archive tool, with the password for encrypted members, to access them.\n\n## Download Selected Contents\n\nSelect archive members or folders and choose **Download** to get a new ZIP containing those items. A selected folder includes its contents. This does not create an archive in storage. See [download limits](../download-and-upload-files/#download-limits).\n\n## Extract Selected Members\n\nOn desktop, open the ZIP in the active pane and a writable physical folder in the other pane. Select members and press **F5** to extract them there. Selected directories include all their contents and empty directories. Archive members cannot be moved; **F6** is unavailable and does not modify the ZIP.\n\nExtraction continues for readable members inside a selected folder. The completion notice reports skipped members and gives separate counts for encryption and unsupported compression.\n\nExtraction can leave partial results after failure or cancellation. Inspect the destination before retrying; see [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n\n## Create an Archive in Storage\n\nUnlike a generated download, **Create archive** writes a persistent ZIP into the destination folder. For files selected inside a ZIP, open a writable physical folder on the **same SMB connection** in the other pane, then choose **Create archive**. Creating an archive from ZIP members is not available for local-drive or mixed-connection destinations.\n\nFor ordinary stored files or folders, select the source items and choose **Create archive** with a writable physical destination. Source items must belong to one connection. The action is unavailable for unsupported source or destination combinations; a ZIP virtual folder cannot be the destination.\n\nCancellation or failure can leave partial results. Inspect the destination and the final operation status before retrying.\n", "2.0": "+++\ntitle = \"Work with ZIP Archives\"\n+++\n\n## Look Inside a ZIP\n\nOpen a ZIP as a virtual folder on an SMB share or paired local drive. Browse its directories and preview supported files inside it without extracting the whole archive. Read-only access is enough for inspection. Local archives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/); SMB archives do not.\n\nSambee cannot preview or extract encrypted members or members with unsupported compression. These members appear in lighter text; hover over a row to see its reason. Use another archive tool, with the password for encrypted members, to access them.\n\n## Download Selected Contents\n\nSelect archive members or folders and choose **Download** to get a new ZIP containing those items. A selected folder includes its contents. This does not create an archive in storage. See [download limits](../download-and-upload-files/#download-limits).\n\n## Extract Selected Members\n\nOn desktop, open the ZIP in the active pane and a writable physical folder in the other pane. Select members and press **F5** to extract them there. Selected directories include all their contents and empty directories. Archive members cannot be moved; **F6** is unavailable and does not modify the ZIP.\n\nExtraction continues for readable members inside a selected folder. The completion notice reports skipped members and gives separate counts for encryption and unsupported compression.\n\nExtraction can leave partial results after failure or cancellation. Inspect the destination before retrying; see [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n\n## Create an Archive in Storage\n\nUnlike a generated download, **Create archive** writes a persistent ZIP into the destination folder. For files selected inside a ZIP, open a writable physical folder on the **same SMB connection** in the other pane, then choose **Create archive**. Creating an archive from ZIP members is not available for local-drive or mixed-connection destinations.\n\nFor ordinary stored files or folders, select the source items and choose **Create archive** with a writable physical destination. Source items must belong to one connection. The action is unavailable for unsupported source or destination combinations; a ZIP virtual folder cannot be the destination.\n\nCancellation or failure can leave partial results. Inspect the destination and the final operation status before retrying.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/organize-and-transfer-files/share-files-on-phones-and-tablets", "parent_id": "section:user-guide/organize-and-transfer-files", "depth": 2, "kind": "page", "label": "share-files-on-phones-and-tablets", "title": "Share Files On Phones And Tablets", "path": "user-guide/organize-and-transfer-files/share-files-on-phones-and-tablets", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "authored"}}, "content_versions": {"2.0": "+++\ntitle = \"Share Files on Phones and Tablets\"\n+++\n\nOn phones and tablets, Sambee integrates with your device's native sharing functionality so that you can send files to other apps.\n\n## Share Stored Files\n\nChoose **Share** from a file's action menu or the selection menu to prepare the stored files. When they are ready, tap **Share** to open your phone or tablet's share sheet. If you select several files, Sambee sends them together. It does not leave files out of your selection.\n\n## Share from a Viewer or Editor\n\nWhen you share from an image or PDF viewer, Sambee shares the version shown in the viewer. This can differ from the stored file if Sambee converted the image or prepared the PDF for viewing. PDF sharing includes the whole document, not just the current page. To share the original stored file, use **Share** in the file list.\n\nFor text and Markdown, choose what to share:\n\n- **Share as file** sends the saved file. It does not save or include unsaved editor changes.\n- **Share as text** sends the loaded text or current editor contents, including unsaved edits. For Markdown, it sends the Markdown text, not the formatted preview.\n\n## If Sharing Is Unavailable or Fails\n\nEven on phones and tablets, sharing support and accepted files depend on the browser and device. A file can be rejected after preparation. Sambee does not send text instead of a file automatically. Choose **Share as text** when that option is available and you want to send text.\n\nIf sharing is unavailable, including on desktop platforms, use **Download**. You can then send the downloaded file through another app on your device.\n\nIf sharing from a viewer fails, the recovery download gives you the same version you tried to share. For several prepared files, download each file separately. If Sambee cannot prepare a text or Markdown file, **Retry** prepares it again. You must then tap **Share** to open the share sheet.\n\n### Get a Report for Support\n\nChoose **Details** in the failure message to get a diagnostic report. It does not include file names, paths, text, file contents, or credentials. Sambee does not upload it automatically. If you cannot copy the report, select its text manually. Closing **Details** leaves the recovery actions available.\n\n### Cancel or Check Delivery\n\nCancelling your phone or tablet's share sheet is not an error. A completed share request does not confirm delivery. Check the receiving app to confirm that it received the files or text.\n"}, "page_contents": {"2.0": "+++\ntitle = \"Share Files on Phones and Tablets\"\n+++\n\nOn phones and tablets, Sambee integrates with your device's native sharing functionality so that you can send files to other apps.\n\n## Share Stored Files\n\nChoose **Share** from a file's action menu or the selection menu to prepare the stored files. When they are ready, tap **Share** to open your phone or tablet's share sheet. If you select several files, Sambee sends them together. It does not leave files out of your selection.\n\n## Share from a Viewer or Editor\n\nWhen you share from an image or PDF viewer, Sambee shares the version shown in the viewer. This can differ from the stored file if Sambee converted the image or prepared the PDF for viewing. PDF sharing includes the whole document, not just the current page. To share the original stored file, use **Share** in the file list.\n\nFor text and Markdown, choose what to share:\n\n- **Share as file** sends the saved file. It does not save or include unsaved editor changes.\n- **Share as text** sends the loaded text or current editor contents, including unsaved edits. For Markdown, it sends the Markdown text, not the formatted preview.\n\n## If Sharing Is Unavailable or Fails\n\nEven on phones and tablets, sharing support and accepted files depend on the browser and device. A file can be rejected after preparation. Sambee does not send text instead of a file automatically. Choose **Share as text** when that option is available and you want to send text.\n\nIf sharing is unavailable, including on desktop platforms, use **Download**. You can then send the downloaded file through another app on your device.\n\nIf sharing from a viewer fails, the recovery download gives you the same version you tried to share. For several prepared files, download each file separately. If Sambee cannot prepare a text or Markdown file, **Retry** prepares it again. You must then tap **Share** to open the share sheet.\n\n### Get a Report for Support\n\nChoose **Details** in the failure message to get a diagnostic report. It does not include file names, paths, text, file contents, or credentials. Sambee does not upload it automatically. If you cannot copy the report, select its text manually. Closing **Details** leaves the recovery actions available.\n\n### Cancel or Check Delivery\n\nCancelling your phone or tablet's share sheet is not an error. A completed share request does not confirm delivery. Check the receiving app to confirm that it received the files or text.\n"}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/view-and-edit-files", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "view-and-edit-files", "title": "View and Edit Files", "path": "user-guide/view-and-edit-files", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/view-and-edit-files/view-images-and-read-documents", "parent_id": "section:user-guide/view-and-edit-files", "depth": 2, "kind": "page", "label": "view-images-and-read-documents", "title": "View Images And Read Documents", "path": "user-guide/view-and-edit-files/view-images-and-read-documents", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.8": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.9": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "1.0": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "2.0": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n"}, "page_contents": {"0.7": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.8": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.9": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "1.0": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "2.0": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/view-and-edit-files/edit-markdown", "parent_id": "section:user-guide/view-and-edit-files", "depth": 2, "kind": "page", "label": "edit-markdown", "title": "Edit Markdown", "path": "user-guide/view-and-edit-files/edit-markdown", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 1}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 2, "diff_removed": 0}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 33, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.8": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "0.9": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "1.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "2.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. You edit Markdown source directly, with highlighted structure and fenced code. Highlighting doesn't change your source text or line layout.\n\nIf another session holds the edit lock, a bottom-center toast explains why editing isn't available. The **Read only** badge and **Retry editing** icon remain after the informational toast closes automatically after 15 seconds. Click Retry or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e when the other editor is closed. Slow access checks show a small spinner beside the filename without moving the document.\n\nIf the lock is lost while editing, Sambee stops changes and retains your draft. On retry, if the saved file changed, choose **Use saved file** or **Keep my draft**. Keeping your draft doesn't save it; review it before choosing Save.\n\n## Edit Rendered Tables\n\nChange cells, rows, and columns in the rendered table view without aligning Markdown markup. Changes become part of the Markdown source and still require **Save** to reach storage.\n\nFor supported code languages, see [Text File Support and Syntax Highlighting](../../reference/text-file-support-and-syntax-highlighting/). For other text files, see [View and Edit Text Files](../view-and-edit-text-files/).\n\n## Large Documents\n\nLarge Markdown previews appear progressively. You can read the text already displayed or close the viewer while loading continues. Search, editing, heading links and the toolbar's Print action become available when the complete document is ready. Printing from the browser menu before then shows a loading notice instead of an incomplete document.\n\nLarge previews can briefly pause while loading, and code colors can arrive after the text. Large Replace All operations show busy feedback before applying the complete replacement, but the editor and indicator can pause during that step. Editing very large tables can also be slow. These limitations don't shorten the document or split a replacement into separate undo steps.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nFinish any input-method composition before saving. Sambee waits for table-cell edits to reach the document before capturing the saved text. If that can't finish, the editor stays open with your changes rather than saving an incomplete cell. Retry Save after the edit finishes.\n\nYou can keep editing during an ordinary Save. Save writes the revision it captured; edits made afterward remain unsaved. If preparation or writing fails, your changes remain available in the editor.\n\nClosing error feedback does not resolve the problem or discard your changes. A failed Save inside a recovery or unsaved-changes dialog stays in that dialog.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor and return to the viewer. If there are unsaved changes, choose **Save** to save them and return to the viewer, **Discard** to return without saving, or **Cancel** to keep editing. If saving fails, the editor stays open with your changes.\n\nFrom the viewer, click the X icon again to return to the file list. This two-step sequence applies to Markdown only. The text editor opens directly and closes straight to the file list, with the same Save, Discard, and Cancel choices for unsaved changes.\n\n## Print Or Save As PDF\n\nIn the Markdown viewer, click the printer icon to open your browser's print dialog. Choose a printer or **Save as PDF** if your browser offers it. You can also use **Print** from the browser menu. Paper size, margins and headers/footers are controlled by that dialog. The suggested PDF filename uses the Markdown document's name when supported by your browser.\n\nThe output contains the rendered document, without Sambee's toolbar or file browser. Text prints black on white in both themes, with compact text sizes independent of the screen view. Long code lines and table cells wrap to fit the page, and images are included. Printing doesn't modify the Markdown file.\n\nPrint is available in the viewer, not the editor. To print your latest changes, save them and return to the viewer first. Closing or cancelling the print dialog leaves the viewer open.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.8": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "0.9": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "1.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "2.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. You edit Markdown source directly, with highlighted structure and fenced code. Highlighting doesn't change your source text or line layout.\n\nIf another session holds the edit lock, a bottom-center toast explains why editing isn't available. The **Read only** badge and **Retry editing** icon remain after the informational toast closes automatically after 15 seconds. Click Retry or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e when the other editor is closed. Slow access checks show a small spinner beside the filename without moving the document.\n\nIf the lock is lost while editing, Sambee stops changes and retains your draft. On retry, if the saved file changed, choose **Use saved file** or **Keep my draft**. Keeping your draft doesn't save it; review it before choosing Save.\n\n## Edit Rendered Tables\n\nChange cells, rows, and columns in the rendered table view without aligning Markdown markup. Changes become part of the Markdown source and still require **Save** to reach storage.\n\nFor supported code languages, see [Text File Support and Syntax Highlighting](../../reference/text-file-support-and-syntax-highlighting/). For other text files, see [View and Edit Text Files](../view-and-edit-text-files/).\n\n## Large Documents\n\nLarge Markdown previews appear progressively. You can read the text already displayed or close the viewer while loading continues. Search, editing, heading links and the toolbar's Print action become available when the complete document is ready. Printing from the browser menu before then shows a loading notice instead of an incomplete document.\n\nLarge previews can briefly pause while loading, and code colors can arrive after the text. Large Replace All operations show busy feedback before applying the complete replacement, but the editor and indicator can pause during that step. Editing very large tables can also be slow. These limitations don't shorten the document or split a replacement into separate undo steps.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nFinish any input-method composition before saving. Sambee waits for table-cell edits to reach the document before capturing the saved text. If that can't finish, the editor stays open with your changes rather than saving an incomplete cell. Retry Save after the edit finishes.\n\nYou can keep editing during an ordinary Save. Save writes the revision it captured; edits made afterward remain unsaved. If preparation or writing fails, your changes remain available in the editor.\n\nClosing error feedback does not resolve the problem or discard your changes. A failed Save inside a recovery or unsaved-changes dialog stays in that dialog.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor and return to the viewer. If there are unsaved changes, choose **Save** to save them and return to the viewer, **Discard** to return without saving, or **Cancel** to keep editing. If saving fails, the editor stays open with your changes.\n\nFrom the viewer, click the X icon again to return to the file list. This two-step sequence applies to Markdown only. The text editor opens directly and closes straight to the file list, with the same Save, Discard, and Cancel choices for unsaved changes.\n\n## Print Or Save As PDF\n\nIn the Markdown viewer, click the printer icon to open your browser's print dialog. Choose a printer or **Save as PDF** if your browser offers it. You can also use **Print** from the browser menu. Paper size, margins and headers/footers are controlled by that dialog. The suggested PDF filename uses the Markdown document's name when supported by your browser.\n\nThe output contains the rendered document, without Sambee's toolbar or file browser. Text prints black on white in both themes, with compact text sizes independent of the screen view. Long code lines and table cells wrap to fit the page, and images are included. Printing doesn't modify the Markdown file.\n\nPrint is available in the viewer, not the editor. To print your latest changes, save them and return to the viewer first. Closing or cancelling the print dialog leaves the viewer open.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/view-and-edit-files/file-locking-and-conflict-resolution", "parent_id": "section:user-guide/view-and-edit-files", "depth": 2, "kind": "page", "label": "file-locking-and-conflict-resolution", "title": "File Locking And Conflict Resolution", "path": "user-guide/view-and-edit-files/file-locking-and-conflict-resolution", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 7, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.8": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.9": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "1.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "2.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Browser Editing\n\nSambee acquires an edit lock before you can edit Markdown or plain-text files. Sambee releases the lock when you leave the editor.\n\nIf another session already holds the lock, the file stays read-only. Use **Retry editing** once the other session has finished.\n\nWhile you're editing, Sambee renews the lock every 30 seconds. Short interruptions retry silently without interrupting your work. After three consecutive renewal failures, a warning appears. It clears when renewal succeeds, and saving still checks the lock.\n\nIf the server confirms that the lock is no longer active or write permission has been denied, the editor immediately becomes read-only and keeps your draft. Use **Retry editing** to regain access. If the saved file changed in the meantime, Sambee asks how to resolve the difference before you continue.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.8": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.9": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "1.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "2.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Browser Editing\n\nSambee acquires an edit lock before you can edit Markdown or plain-text files. Sambee releases the lock when you leave the editor.\n\nIf another session already holds the lock, the file stays read-only. Use **Retry editing** once the other session has finished.\n\nWhile you're editing, Sambee renews the lock every 30 seconds. Short interruptions retry silently without interrupting your work. After three consecutive renewal failures, a warning appears. It clears when renewal succeeds, and saving still checks the lock.\n\nIf the server confirms that the lock is no longer active or write permission has been denied, the editor immediately becomes read-only and keeps your draft. Use **Retry editing** to regain access. If the saved file changed in the meantime, Sambee asks how to resolve the difference before you continue.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/view-and-edit-files/view-and-edit-text-files", "parent_id": "section:user-guide/view-and-edit-files", "depth": 2, "kind": "page", "label": "view-and-edit-text-files", "title": "View And Edit Text Files", "path": "user-guide/view-and-edit-files/view-and-edit-text-files", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "authored"}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 13, "diff_removed": 5}}, "content_versions": {"0.8": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "0.9": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "1.0": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "2.0": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files directly in their existing storage. **Save** writes to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/). See [Text File Support and Syntax Highlighting](../../reference/text-file-support-and-syntax-highlighting/) for formats and limits, or [Edit Markdown](../edit-markdown/) for rendered table editing.\n\n## Saving and Locks\n\nFiles without write permission, files on read-only connections, ZIP members, and files above the configured editing limit stay read-only. You can still read or download them.\n\nEditing requires a file lock. If editing is unavailable, close the other edit session, then use **Retry editing**. If the lock is lost, Sambee stops changes and retains your draft. If the saved file changed, choose **Use saved file** or **Keep my draft** when retrying. Keeping a draft does not save it; review it before Save. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/).\n\nYou can edit during an ordinary Save. Save writes the revision captured when it began; later edits remain unsaved. A failed save keeps your changes in the editor. Finish input-method composition before saving.\n\n## Unsaved Changes and Recovery\n\nThe text editor closes directly to the file list. With unsaved changes, **Save** writes them before leaving, **Discard** leaves without saving, and **Cancel** keeps editing. A failed save keeps the editor open. Navigation does not undo saved changes or restore discarded edits.\n\nIf sign-in interrupts editing, eligible drafts can be stored in this browser tab. Recovery is not a substitute for saving. See [Recover Unsaved Edits](../recover-unsaved-edits/).\n\nFor an installed application instead, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n"}, "page_contents": {"0.8": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "0.9": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "1.0": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "2.0": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files directly in their existing storage. **Save** writes to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/). See [Text File Support and Syntax Highlighting](../../reference/text-file-support-and-syntax-highlighting/) for formats and limits, or [Edit Markdown](../edit-markdown/) for rendered table editing.\n\n## Saving and Locks\n\nFiles without write permission, files on read-only connections, ZIP members, and files above the configured editing limit stay read-only. You can still read or download them.\n\nEditing requires a file lock. If editing is unavailable, close the other edit session, then use **Retry editing**. If the lock is lost, Sambee stops changes and retains your draft. If the saved file changed, choose **Use saved file** or **Keep my draft** when retrying. Keeping a draft does not save it; review it before Save. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/).\n\nYou can edit during an ordinary Save. Save writes the revision captured when it began; later edits remain unsaved. A failed save keeps your changes in the editor. Finish input-method composition before saving.\n\n## Unsaved Changes and Recovery\n\nThe text editor closes directly to the file list. With unsaved changes, **Save** writes them before leaving, **Discard** leaves without saving, and **Cancel** keeps editing. A failed save keeps the editor open. Navigation does not undo saved changes or restore discarded edits.\n\nIf sign-in interrupts editing, eligible drafts can be stored in this browser tab. Recovery is not a substitute for saving. See [Recover Unsaved Edits](../recover-unsaved-edits/).\n\nFor an installed application instead, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/view-and-edit-files/recover-unsaved-edits", "parent_id": "section:user-guide/view-and-edit-files", "depth": 2, "kind": "page", "label": "recover-unsaved-edits", "title": "Recover Unsaved Edits", "path": "user-guide/view-and-edit-files/recover-unsaved-edits", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 36, "diff_removed": 3}}, "content_versions": {"0.9": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "1.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "2.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\nThe pre-sign-in snapshot is a best-effort attempt. Sign-in continues even if a draft cannot be stored; it does not wait for unfinished editor input or save the file. Save important work regularly.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- When Sambee offers an unsaved local draft, choose **Resume editing** to return to it, or **Discard draft** to keep the saved file.\n- If the remote file changed, review the recovery choice carefully. Sambee doesn't overwrite the remote version automatically.\n- Save the restored draft when you're ready. Sambee removes its recovery copy once the current draft is saved or when you deliberately discard it. Edits made while an earlier save is still in progress remain unsaved.\n\n## Recovery Limits\n\n### Moved or Deleted Files\n\nIf the file or its folder is moved or deleted while you edit, keep the editor open. A directory refresh can open an accessible parent folder without closing the editor or changing its unsaved text.\n\nSave from an active edit session can recreate a deleted file at its original path. It does not follow a moved file to its new location. SMB saves require the parent folder to exist; local-drive saves can recreate parent folders on an available drive.\n\nA failed save keeps the draft. Use the available draft recovery or download action to keep your work. If editing becomes unavailable, use the explicit editing retry action and review any conflict before saving. Sambee does not silently acquire a new lock after a failed save.\n\nAccess errors and connection failures do not mean the file was deleted. Check access or restore the connection, then retry. Do not discard the draft unless you no longer need its changes.\n\nA normal save can overwrite changes made at the same file path. Sambee does not check for all external changes before each write. If the write succeeds but updated file information cannot be read, the save remains successful; Sambee does not repeat the write automatically.\n\n### Notifications and Connection Recovery\n\nRecovery notifications appear at the bottom center of the application, not inside a browser pane. Informational results, including automatic parent-folder recovery, close after 6 seconds. Browser failures, pairing notices, monitoring failures, and connection status notices close after 10 seconds. Editor errors and safety warnings, including save failures, close after 15 seconds. The timer pauses while you point to the notification or use its controls with the keyboard. Closing a notification does not save a draft, restore a connection, or remove recovery data. Use Next notification when more than one condition needs attention.\n\nFile and folder failure notifications show the problem first. A smaller line below it identifies the connection and failed file or folder. Long paths are shortened to fit on one line, keeping the connection and the end of the path where space permits. Point to a shortened value to see the complete path from the connection's root. The full value also remains available to screen readers. The path identifies the failed target, not a different folder that you opened later. After automatic parent-folder recovery, this line still identifies the original missing folder.\n\nNotifications stay open without a timer only while they provide Cancel for an active upload, download, or share preparation, or Share and Cancel for files ready to share. Sharing after confirmation uses the normal 6-second information timeout. A notification closing does not cancel an active operation. Unsaved-change and other decision dialogs do not close on a timer.\n\nRetry applies to the file or folder that failed, even after you select another row or pane. A failed folder navigation keeps the previous usable folder visible. If no folder can load, the list area shows the error and recovery actions instead of an empty list. A folder that loaded with no files remains a normal empty folder.\n\nRefresh reloads the displayed folder. It does not repeat a failed file launch or open a different failed folder. The existing header warning control opens connection recovery actions after a notification closes automatically or you close it manually. No additional warning or progress controls are added when a notification closes.\n\nIf automatic updates stop, use **Automatic updates stopped** to retry monitoring. This control remains available after you close its notification. Monitoring is active again only after the subscription is confirmed. A backend connection status distinguishes reconnection from unavailability. Companion recovery remains available through Local Drives, including when no editor is open. A signature error can require **Reload Sambee**. Unsaved changes still require your decision before reload.\n\nIf a document cannot load, its viewer shows the error with Retry and Close. A missing image in the gallery shows an error for that image; use Retry, select another image, or close the viewer. Sambee does not keep the previous document open until the next document finishes loading.\n\n### Browser Storage\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\nAn unfinished edit may not be recoverable when the browser suspends or terminates the page. A successful recovery checkpoint isn't a file save or a guarantee that the draft will survive closing the tab.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "1.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "2.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\nThe pre-sign-in snapshot is a best-effort attempt. Sign-in continues even if a draft cannot be stored; it does not wait for unfinished editor input or save the file. Save important work regularly.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- When Sambee offers an unsaved local draft, choose **Resume editing** to return to it, or **Discard draft** to keep the saved file.\n- If the remote file changed, review the recovery choice carefully. Sambee doesn't overwrite the remote version automatically.\n- Save the restored draft when you're ready. Sambee removes its recovery copy once the current draft is saved or when you deliberately discard it. Edits made while an earlier save is still in progress remain unsaved.\n\n## Recovery Limits\n\n### Moved or Deleted Files\n\nIf the file or its folder is moved or deleted while you edit, keep the editor open. A directory refresh can open an accessible parent folder without closing the editor or changing its unsaved text.\n\nSave from an active edit session can recreate a deleted file at its original path. It does not follow a moved file to its new location. SMB saves require the parent folder to exist; local-drive saves can recreate parent folders on an available drive.\n\nA failed save keeps the draft. Use the available draft recovery or download action to keep your work. If editing becomes unavailable, use the explicit editing retry action and review any conflict before saving. Sambee does not silently acquire a new lock after a failed save.\n\nAccess errors and connection failures do not mean the file was deleted. Check access or restore the connection, then retry. Do not discard the draft unless you no longer need its changes.\n\nA normal save can overwrite changes made at the same file path. Sambee does not check for all external changes before each write. If the write succeeds but updated file information cannot be read, the save remains successful; Sambee does not repeat the write automatically.\n\n### Notifications and Connection Recovery\n\nRecovery notifications appear at the bottom center of the application, not inside a browser pane. Informational results, including automatic parent-folder recovery, close after 6 seconds. Browser failures, pairing notices, monitoring failures, and connection status notices close after 10 seconds. Editor errors and safety warnings, including save failures, close after 15 seconds. The timer pauses while you point to the notification or use its controls with the keyboard. Closing a notification does not save a draft, restore a connection, or remove recovery data. Use Next notification when more than one condition needs attention.\n\nFile and folder failure notifications show the problem first. A smaller line below it identifies the connection and failed file or folder. Long paths are shortened to fit on one line, keeping the connection and the end of the path where space permits. Point to a shortened value to see the complete path from the connection's root. The full value also remains available to screen readers. The path identifies the failed target, not a different folder that you opened later. After automatic parent-folder recovery, this line still identifies the original missing folder.\n\nNotifications stay open without a timer only while they provide Cancel for an active upload, download, or share preparation, or Share and Cancel for files ready to share. Sharing after confirmation uses the normal 6-second information timeout. A notification closing does not cancel an active operation. Unsaved-change and other decision dialogs do not close on a timer.\n\nRetry applies to the file or folder that failed, even after you select another row or pane. A failed folder navigation keeps the previous usable folder visible. If no folder can load, the list area shows the error and recovery actions instead of an empty list. A folder that loaded with no files remains a normal empty folder.\n\nRefresh reloads the displayed folder. It does not repeat a failed file launch or open a different failed folder. The existing header warning control opens connection recovery actions after a notification closes automatically or you close it manually. No additional warning or progress controls are added when a notification closes.\n\nIf automatic updates stop, use **Automatic updates stopped** to retry monitoring. This control remains available after you close its notification. Monitoring is active again only after the subscription is confirmed. A backend connection status distinguishes reconnection from unavailability. Companion recovery remains available through Local Drives, including when no editor is open. A signature error can require **Reload Sambee**. Unsaved changes still require your decision before reload.\n\nIf a document cannot load, its viewer shows the error with Retry and Close. A missing image in the gallery shows an error for that image; use Retry, select another image, or close the viewer. Sambee does not keep the previous document open until the next document finishes loading.\n\n### Browser Storage\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\nAn unfinished edit may not be recoverable when the browser suspends or terminates the page. A successful recovery checkpoint isn't a file save or a guarantee that the draft will survive closing the tab.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/use-local-drives-and-desktop-apps", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "use-local-drives-and-desktop-apps", "title": "Use Local Drives and Desktop Apps", "path": "user-guide/use-local-drives-and-desktop-apps", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/use-local-drives-and-desktop-apps/install-and-pair-the-companion-app", "parent_id": "section:user-guide/use-local-drives-and-desktop-apps", "depth": 2, "kind": "page", "label": "install-and-pair-the-companion-app", "title": "Install And Pair The Companion App", "path": "user-guide/use-local-drives-and-desktop-apps/install-and-pair-the-companion-app", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 17, "diff_removed": 4}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 19, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair This Browser With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee and Companion both display a verification code. Confirm that both codes match, then finish pairing. Sambee should now show a check mark next to **This browser is paired**.\n\nPairing is scoped to the current browser origin and browser profile, not to the whole computer. If you use Sambee from a different browser, a different browser profile, or a different Sambee site origin, approve that browser separately.\n\nOnce this browser is paired with Companion, local drives on your computer appear in Sambee's connection list.\n", "0.8": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "0.9": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "1.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "2.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\nOpen Sambee over HTTPS before pairing from another computer or a network address. Browsers don't provide the cryptographic APIs needed by Companion on ordinary HTTP sites. Local development on `http://localhost` is an exception. If **Local Drives** warns that a secure browser context with Web Crypto support is unavailable, use HTTPS; if you're already using HTTPS, check that your browser supports and permits Web Crypto. You don't need HTTPS to download the Companion installer.\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nPairing also lets that server manage Companion theme, localization, and directory-search settings. The most recently paired server is authoritative, even if other servers remain paired for file access. Pair the intended server again to change authority. No separate settings approval is required.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee verifies local access and shows a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- Settings synchronize automatically while a signed-in Sambee tab is active. Failed delivery keeps the last valid settings; it does not disable directory search.\n- Removing the authoritative pairing keeps the last valid settings but does not select another server automatically.\n\n## Restore Local-Drive Access\n\nIf a local drive reports a pairing error, open **Settings** \u003e **Local Drives** from the file-list alert. **Ready** means the browser has passed an authenticated pairing check; having a stored pairing alone is not enough.\n\n1. If Companion needs an update, install the available version, restart Companion, and reload the Sambee page. Re-pairing will not resolve an incompatible version.\n1. If Sambee needs an update, reload the page. If the version mismatch remains, update Sambee. Updating Companion or re-pairing will not fix a newer Companion protocol.\n1. If the file-list alert says this browser isn't paired, open **Local Drives** and select **Pair This Browser**. Reloading alone won't restore a missing or removed pairing.\n1. If Companion rejects the browser's signature, reload the Sambee page first. A page left open across an update may still use the previous authentication protocol.\n1. Run **Test Current Pairing**. If it still fails with a signature error after reloading, use **Pair This Browser** and approve the new code in Companion.\n\nIf Sambee cannot check the pairing status, select **Retry**. Wait for a confirmed status before starting a new pairing. Companion pairing secrets do not expire on a 30-day timer. An unavailable Companion or a temporary failed check does not mean you need to re-pair.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair This Browser With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee and Companion both display a verification code. Confirm that both codes match, then finish pairing. Sambee should now show a check mark next to **This browser is paired**.\n\nPairing is scoped to the current browser origin and browser profile, not to the whole computer. If you use Sambee from a different browser, a different browser profile, or a different Sambee site origin, approve that browser separately.\n\nOnce this browser is paired with Companion, local drives on your computer appear in Sambee's connection list.\n", "0.8": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "0.9": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "1.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "2.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\nOpen Sambee over HTTPS before pairing from another computer or a network address. Browsers don't provide the cryptographic APIs needed by Companion on ordinary HTTP sites. Local development on `http://localhost` is an exception. If **Local Drives** warns that a secure browser context with Web Crypto support is unavailable, use HTTPS; if you're already using HTTPS, check that your browser supports and permits Web Crypto. You don't need HTTPS to download the Companion installer.\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nPairing also lets that server manage Companion theme, localization, and directory-search settings. The most recently paired server is authoritative, even if other servers remain paired for file access. Pair the intended server again to change authority. No separate settings approval is required.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee verifies local access and shows a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- Settings synchronize automatically while a signed-in Sambee tab is active. Failed delivery keeps the last valid settings; it does not disable directory search.\n- Removing the authoritative pairing keeps the last valid settings but does not select another server automatically.\n\n## Restore Local-Drive Access\n\nIf a local drive reports a pairing error, open **Settings** \u003e **Local Drives** from the file-list alert. **Ready** means the browser has passed an authenticated pairing check; having a stored pairing alone is not enough.\n\n1. If Companion needs an update, install the available version, restart Companion, and reload the Sambee page. Re-pairing will not resolve an incompatible version.\n1. If Sambee needs an update, reload the page. If the version mismatch remains, update Sambee. Updating Companion or re-pairing will not fix a newer Companion protocol.\n1. If the file-list alert says this browser isn't paired, open **Local Drives** and select **Pair This Browser**. Reloading alone won't restore a missing or removed pairing.\n1. If Companion rejects the browser's signature, reload the Sambee page first. A page left open across an update may still use the previous authentication protocol.\n1. Run **Test Current Pairing**. If it still fails with a signature error after reloading, use **Pair This Browser** and approve the new code in Companion.\n\nIf Sambee cannot check the pairing status, select **Retry**. Wait for a confirmed status before starting a new pairing. Companion pairing secrets do not expire on a 30-day timer. An unavailable Companion or a temporary failed check does not mean you need to re-pair.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/use-local-drives-and-desktop-apps/access-local-drives", "parent_id": "section:user-guide/use-local-drives-and-desktop-apps", "depth": 2, "kind": "page", "label": "access-local-drives", "title": "Access Local Drives", "path": "user-guide/use-local-drives-and-desktop-apps/access-local-drives", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.8": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.9": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "1.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "2.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.8": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.9": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "1.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "2.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/use-local-drives-and-desktop-apps/edit-files-in-desktop-apps", "parent_id": "section:user-guide/use-local-drives-and-desktop-apps", "depth": 2, "kind": "page", "label": "edit-files-in-desktop-apps", "title": "Edit Files In Desktop Apps", "path": "user-guide/use-local-drives-and-desktop-apps/edit-files-in-desktop-apps", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "0.8": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "0.9": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "1.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "2.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "0.8": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "0.9": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "1.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "2.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/use-local-drives-and-desktop-apps/desktop-app-picker", "parent_id": "section:user-guide/use-local-drives-and-desktop-apps", "depth": 2, "kind": "page", "label": "desktop-app-picker", "title": "Desktop App Picker", "path": "user-guide/use-local-drives-and-desktop-apps/desktop-app-picker", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.8": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.9": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "1.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "2.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.8": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.9": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "1.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "2.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/troubleshooting", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "troubleshooting", "title": "Troubleshooting", "path": "user-guide/troubleshooting", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/troubleshooting/common-user-problems", "parent_id": "section:user-guide/troubleshooting", "depth": 2, "kind": "page", "label": "common-user-problems", "title": "Common User Problems", "path": "user-guide/troubleshooting/common-user-problems", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 6, "diff_removed": 9}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 1, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing for the current browser profile.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If the browser is not paired, start pairing again for this browser.\n1. If Local Drives reports that pairing needs repair, repair the pairing so Sambee can store a fresh browser-side secret.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe desktop-editing session may have expired or been interrupted.\n\nTypical signs are that the **Done Editing** window says the session expired, authentication failed, the lock was lost, or recovery is required.\n\nStart by reopening the file from Sambee so Companion can establish a fresh edit session and lock context.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "0.8": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "0.9": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "1.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "2.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files on Phones and Tablets](../../organize-and-transfer-files/share-files-on-phones-and-tablets/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing for the current browser profile.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If the browser is not paired, start pairing again for this browser.\n1. If Local Drives reports that pairing needs repair, repair the pairing so Sambee can store a fresh browser-side secret.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe desktop-editing session may have expired or been interrupted.\n\nTypical signs are that the **Done Editing** window says the session expired, authentication failed, the lock was lost, or recovery is required.\n\nStart by reopening the file from Sambee so Companion can establish a fresh edit session and lock context.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "0.8": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "0.9": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "1.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "2.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files on Phones and Tablets](../../organize-and-transfer-files/share-files-on-phones-and-tablets/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/reference", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "reference", "title": "Reference", "path": "user-guide/reference", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/reference/supported-file-formats", "parent_id": "section:user-guide/reference", "depth": 2, "kind": "page", "label": "supported-file-formats", "title": "Supported File Formats", "path": "user-guide/reference/supported-file-formats", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 2, "diff_removed": 0}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "branched", "source_version": "0.8", "diff_added": 11, "diff_removed": 3}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 1, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "0.8": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "0.9": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "1.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "2.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code | See [Text File Support and Syntax Highlighting](../text-file-support-and-syntax-highlighting/) for extensions, filename matches, and plain-text formats. | Open directly in the text editor, read-only when editing isn't available. Dedicated viewers and saved viewer preferences take precedence. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "0.8": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "0.9": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "1.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "2.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code | See [Text File Support and Syntax Highlighting](../text-file-support-and-syntax-highlighting/) for extensions, filename matches, and plain-text formats. | Open directly in the text editor, read-only when editing isn't available. Dedicated viewers and saved viewer preferences take precedence. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/reference/text-file-support-and-syntax-highlighting", "parent_id": "section:user-guide/reference", "depth": 2, "kind": "page", "label": "text-file-support-and-syntax-highlighting", "title": "Text File Support And Syntax Highlighting", "path": "user-guide/reference/text-file-support-and-syntax-highlighting", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "authored"}}, "content_versions": {"2.0": "+++\ntitle = \"Text File Support and Syntax Highlighting\"\n+++\n\nUse this reference to check which files open in the text editor and which language labels you can use in Markdown code blocks. Sambee uses the same syntax highlighting for the text editor, Markdown source, and code blocks in Markdown previews.\n\n## Text File Support\n\nFiles with an extension or special filename listed below open in the text editor by default, with two exceptions: `.md` and `.markdown` open in the Markdown viewer, and `.svg` opens in the image viewer. A saved viewer preference or the file's MIME type can override the filename-based choice.\n\nThe filename also selects the highlighting language:\n\n- Special filenames take priority over extensions. Their case rules vary: `Dockerfile` requires that spelling, while `nginx.conf` matches in any case.\n- Extensions aren't case-sensitive. Only the final suffix counts, so `project.cmake.in` uses Properties highlighting through `.in`, not CMake.\n- Shared extensions select one language: `.m` uses Mathematica, `.sig` uses PGP, and `.v` uses SystemVerilog.\n\nPlain-text formats such as `.txt` and `.log` open in the text editor without highlighting. Unmatched files don't automatically open as text, but you can choose the text editor from the viewer picker; without a language match, they use plain text.\n\nFor images, PDFs, archives, and other supported formats, see [Supported File Formats](../supported-file-formats/).\n\n## Markdown Code Block Languages\n\nPut a language label immediately after the opening three backticks. For example, `py` selects Python:\n\n````markdown\n```py\ndef greet(name):\n\treturn f\"Hello, {name}!\"\n```\n````\n\nLabels aren't case-sensitive. Labels on the same table row are interchangeable, so `python` works just like `py`. Sambee reads only the first whitespace-separated word after the opening fence; a language's full name works only if it's listed as a label.\n\nUnlabelled blocks and unknown labels use plain text. To request plain text explicitly, use `text`, `txt`, `plaintext`, `plain`, or `none`. Very large code blocks can also remain plain text without losing their contents.\n\n## File and Language Reference\n\nUse the file column to look up a file and the Markdown column to choose a code block label. **None** in the file or viewer column means the language is available only in Markdown code blocks. **None** in the Markdown column means there's no accepted code block label for that format. Viewer choices assume no MIME-type or saved-preference override.\n\n| Language or format | File extensions or names | Markdown labels | Default viewer |\n|---|---|---|---|\n| APL | `.dyalog`, `.apl` | `apl` | Text |\n| ASN.1 | `.asn`, `.asn1` | `asn.1` | Text |\n| Asterisk | `extensions.conf` | `asterisk` | Text |\n| Brainfuck | `.b`, `.bf` | `brainfuck` | Text |\n| C | `.c`, `.h`, `.ino` | `c` | Text |\n| C# | `.cs` | `cs`, `csharp`, `c#` | Text |\n| C++ | `.cpp`, `.c++`, `.cc`, `.cxx`, `.hpp`, `.h++`, `.hh`, `.hxx` | `cpp`, `c++` | Text |\n| Clojure | `.clj`, `.cljc`, `.cljx` | `clojure` | Text |\n| ClojureScript | `.cljs` | `clojurescript` | Text |\n| Closure Stylesheets (GSS) | `.gss` | None | Text |\n| CMake | `.cmake`, `CMakeLists.txt` | `cmake` | Text |\n| COBOL | `.cob`, `.cpy` | `cobol` | Text |\n| CoffeeScript | `.coffee` | `coffee`, `coffee-script`, `coffeescript` | Text |\n| Common Lisp | `.cl`, `.lisp`, `.el` | `lisp` | Text |\n| CQL (Cassandra) | `.cql` | `cql`, `cassandra` | Text |\n| Crystal | `.cr` | `crystal` | Text |\n| CSS | `.css` | `css` | Text |\n| Cypher | `.cyp`, `.cypher` | `cypher` | Text |\n| Cython | `.pyx`, `.pxd`, `.pxi` | `cython` | Text |\n| D | `.d` | `d` | Text |\n| Dart | `.dart` | `dart` | Text |\n| Diff | `.diff`, `.patch` | `diff` | Text |\n| Dockerfile | `Dockerfile` | `docker`, `dockerfile` | Text |\n| DTD | `.dtd` | `dtd` | Text |\n| Dylan | `.dylan`, `.dyl`, `.intr` | `dylan` | Text |\n| EBNF | None | `ebnf` | None |\n| ECL | `.ecl` | `ecl` | Text |\n| edn | `.edn` | `edn` | Text |\n| Eiffel | `.e` | `eiffel` | Text |\n| Elm | `.elm` | `elm` | Text |\n| Erlang | `.erl` | `erlang` | Text |\n| Esper | None | `esper` | None |\n| F# | `.fs` | `fsharp`, `f#` | Text |\n| Factor | `.factor` | `factor` | Text |\n| FCL | None | `fcl` | None |\n| Forth | `.forth`, `.fth`, `.4th` | `forth` | Text |\n| Fortran | `.f`, `.for`, `.f77`, `.f90`, `.f95` | `fortran` | Text |\n| Gas (GNU assembler) | `.s` | `gas` | Text |\n| Gherkin | `.feature` | `gherkin` | Text |\n| Go | `.go` | `go` | Text |\n| Groovy | `.groovy`, `.gradle`, `Jenkinsfile` | `groovy` | Text |\n| Haskell | `.hs` | `haskell` | Text |\n| Haxe | `.hx` | `haxe` | Text |\n| HTML | `.html`, `.htm`, `.handlebars`, `.hbs` | `html`, `htm`, `xhtml` | Text |\n| HTTP | None | `http` | None |\n| HXML | `.hxml` | `hxml` | Text |\n| IDL | `.pro` | `idl` | Text |\n| Java | `.java` | `java` | Text |\n| JavaScript | `.js`, `.mjs`, `.cjs` | `js`, `javascript`, `ecmascript`, `node` | Text |\n| Jinja | `.j2`, `.jinja`, `.jinja2` | `jinja` | Text |\n| JSON | `.json`, `.map` | `json`, `json5` | Text |\n| JSON-LD | `.jsonld` | `jsonld`, `json-ld` | Text |\n| JSX | `.jsx` | `jsx` | Text |\n| Julia | `.jl` | `julia` | Text |\n| Kotlin | `.kt`, `.kts` | `kt`, `kotlin` | Text |\n| LaTeX | `.text`, `.ltx`, `.tex` | `tex`, `latex` | Text |\n| LESS | `.less` | `less` | Text |\n| Liquid | `.liquid` | `liquid` | Text |\n| LiveScript | `.ls` | `ls`, `livescript` | Text |\n| Lua | `.lua` | `lua` | Text |\n| MariaDB SQL | None | `mariadb` | None |\n| Markdown | `.md`, `.markdown` | `md`, `markdown` | Markdown |\n| Markdown source | `.mkd` | `md`, `markdown` | Text |\n| Mathematica | `.m`, `.nb`, `.wl`, `.wls` | `mathematica` | Text |\n| Mbox | `.mbox` | `mbox` | Text |\n| mIRC | `.mrc` | `mirc` | Text |\n| Modelica | `.mo` | `modelica` | Text |\n| MS SQL | None | `mssql` | None |\n| MscGen | `.mscgen`, `.mscin`, `.msc` | `mscgen` | Text |\n| MsGenny | `.msgenny` | `msgenny` | Text |\n| MUMPS | `.mps` | `mumps` | Text |\n| MySQL | None | `mysql` | None |\n| Nginx | Names ending in `.conf` that contain `nginx`, such as `nginx.conf` | `nginx` | Text |\n| NSIS | `.nsh`, `.nsi` | `nsis` | Text |\n| NTriples | `.nt`, `.nq` | `ntriples` | Text |\n| Objective-C | None | `objective-c`, `objc` | None |\n| Objective-C++ | `.mm` | `objective-c++`, `objc++` | Text |\n| OCaml | `.ml`, `.mli`, `.mll`, `.mly` | `ocaml` | Text |\n| Octave | None | `octave` | None |\n| Oz | `.oz` | `oz` | Text |\n| Pascal | `.p`, `.pas` | `pascal` | Text |\n| Perl | `.pl`, `.pm` | `perl` | Text |\n| PGP | `.asc`, `.pgp`, `.sig` | `pgp`, `asciiarmor` | Text |\n| PHP | `.php`, `.php3`, `.php4`, `.php5`, `.php7`, `.phtml` | `php` | Text |\n| Pig | `.pig` | `pig` | Text |\n| Plain text (no highlighting) | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | `text`, `txt`, `plaintext`, `plain`, `none` | Text |\n| PLSQL | `.pls` | `plsql` | Text |\n| PostgreSQL | None | `postgresql` | None |\n| PowerShell | `.ps1`, `.psd1`, `.psm1` | `ps1`, `powershell` | Text |\n| Properties files | `.properties`, `.ini`, `.in` | `ini`, `properties` | Text |\n| ProtoBuf | `.proto` | `protobuf` | Text |\n| Pug | `.pug`, `.jade` | `jade`, `pug` | Text |\n| Puppet | `.pp` | `puppet` | Text |\n| Python | `.build`, `.bzl`, `.py`, `.pyw`, `BUCK`, `BUILD` | `py`, `python` | Text |\n| Q | `.q` | `q` | Text |\n| R | `.r` | `r`, `rscript` | Text |\n| RPM Spec | `.spec` | None | Text |\n| Ruby | `.rb`, `Gemfile`, `Rakefile` | `rb`, `ruby`, `jruby`, `macruby`, `rake`, `rbx` | Text |\n| Rust | `.rs` | `rs`, `rust` | Text |\n| SAS | `.sas` | `sas` | Text |\n| Sass | `.sass` | `sass` | Text |\n| Scala | `.scala` | `scala` | Text |\n| Scheme | `.scm`, `.ss` | `scheme` | Text |\n| SCSS | `.scss` | `scss` | Text |\n| Shell | `.sh`, `.ksh`, `.bash`, `PKGBUILD` | `sh`, `bash`, `zsh`, `shell`, `shellsession`, `console` | Text |\n| Sieve | `.siv`, `.sieve` | `sieve` | Text |\n| Smalltalk | `.st` | `smalltalk` | Text |\n| SML | `.sml`, `.fun`, `.smackspec` | `sml` | Text |\n| Solr | None | `solr` | None |\n| SPARQL | `.rq`, `.sparql` | `sparql`, `sparul` | Text |\n| Spreadsheet | None | `excel`, `formula`, `spreadsheet` | None |\n| SQL | `.sql` | `sql` | Text |\n| SQLite | None | `sqlite` | None |\n| Squirrel | `.nut` | `squirrel` | Text |\n| sTeX | None | `stex` | None |\n| Stylus | `.styl` | `stylus` | Text |\n| SVG (XML highlighting) | `.svg` | `xml`, `rss`, `wsdl`, `xsd` | Image |\n| Swift | `.swift` | `swift` | Text |\n| SystemVerilog | `.v`, `.sv`, `.svh` | `systemverilog` | Text |\n| Tcl | `.tcl` | `tcl` | Text |\n| Textile | `.textile` | `textile` | Text |\n| TiddlyWiki | None | `tiddlywiki` | None |\n| TOML | `.toml` | `toml` | Text |\n| Troff | `.1`, `.2`, `.3`, `.4`, `.5`, `.6`, `.7`, `.8`, `.9` | `troff` | Text |\n| TSX | `.tsx` | `tsx` | Text |\n| TTCN | `.ttcn`, `.ttcn3`, `.ttcnpp` | `ttcn` | Text |\n| TTCN_CFG | `.cfg` | `ttcn_cfg` | Text |\n| Turtle | `.ttl` | `turtle` | Text |\n| TypeScript | `.ts`, `.mts`, `.cts` | `ts`, `typescript` | Text |\n| VB.NET | `.vb` | `vb.net` | Text |\n| VBScript | `.vbs` | `vbscript` | Text |\n| Velocity | `.vtl` | `velocity` | Text |\n| Verilog | None | `verilog` | None |\n| VHDL | `.vhd`, `.vhdl` | `vhdl` | Text |\n| Vue | `.vue` | `vue` | Text |\n| Web IDL | `.webidl` | None | Text |\n| WebAssembly | `.wat`, `.wast` | `webassembly` | Text |\n| XML | `.xml`, `.xsl`, `.xsd` | `xml`, `rss`, `wsdl`, `xsd` | Text |\n| XQuery | `.xy`, `.xquery`, `.xq`, `.xqm`, `.xqy` | `xquery` | Text |\n| X\u00f9 | `.xu` | `x\u00f9` | Text |\n| Yacas | `.ys` | `yacas` | Text |\n| YAML | `.yaml`, `.yml` | `yaml`, `yml` | Text |\n| Z80 | `.z80` | `z80` | Text |\n\n## Related Guides\n\n- [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/)\n- [Edit Markdown](../../view-and-edit-files/edit-markdown/)\n- [Supported File Formats](../supported-file-formats/)\n"}, "page_contents": {"2.0": "+++\ntitle = \"Text File Support and Syntax Highlighting\"\n+++\n\nUse this reference to check which files open in the text editor and which language labels you can use in Markdown code blocks. Sambee uses the same syntax highlighting for the text editor, Markdown source, and code blocks in Markdown previews.\n\n## Text File Support\n\nFiles with an extension or special filename listed below open in the text editor by default, with two exceptions: `.md` and `.markdown` open in the Markdown viewer, and `.svg` opens in the image viewer. A saved viewer preference or the file's MIME type can override the filename-based choice.\n\nThe filename also selects the highlighting language:\n\n- Special filenames take priority over extensions. Their case rules vary: `Dockerfile` requires that spelling, while `nginx.conf` matches in any case.\n- Extensions aren't case-sensitive. Only the final suffix counts, so `project.cmake.in` uses Properties highlighting through `.in`, not CMake.\n- Shared extensions select one language: `.m` uses Mathematica, `.sig` uses PGP, and `.v` uses SystemVerilog.\n\nPlain-text formats such as `.txt` and `.log` open in the text editor without highlighting. Unmatched files don't automatically open as text, but you can choose the text editor from the viewer picker; without a language match, they use plain text.\n\nFor images, PDFs, archives, and other supported formats, see [Supported File Formats](../supported-file-formats/).\n\n## Markdown Code Block Languages\n\nPut a language label immediately after the opening three backticks. For example, `py` selects Python:\n\n````markdown\n```py\ndef greet(name):\n\treturn f\"Hello, {name}!\"\n```\n````\n\nLabels aren't case-sensitive. Labels on the same table row are interchangeable, so `python` works just like `py`. Sambee reads only the first whitespace-separated word after the opening fence; a language's full name works only if it's listed as a label.\n\nUnlabelled blocks and unknown labels use plain text. To request plain text explicitly, use `text`, `txt`, `plaintext`, `plain`, or `none`. Very large code blocks can also remain plain text without losing their contents.\n\n## File and Language Reference\n\nUse the file column to look up a file and the Markdown column to choose a code block label. **None** in the file or viewer column means the language is available only in Markdown code blocks. **None** in the Markdown column means there's no accepted code block label for that format. Viewer choices assume no MIME-type or saved-preference override.\n\n| Language or format | File extensions or names | Markdown labels | Default viewer |\n|---|---|---|---|\n| APL | `.dyalog`, `.apl` | `apl` | Text |\n| ASN.1 | `.asn`, `.asn1` | `asn.1` | Text |\n| Asterisk | `extensions.conf` | `asterisk` | Text |\n| Brainfuck | `.b`, `.bf` | `brainfuck` | Text |\n| C | `.c`, `.h`, `.ino` | `c` | Text |\n| C# | `.cs` | `cs`, `csharp`, `c#` | Text |\n| C++ | `.cpp`, `.c++`, `.cc`, `.cxx`, `.hpp`, `.h++`, `.hh`, `.hxx` | `cpp`, `c++` | Text |\n| Clojure | `.clj`, `.cljc`, `.cljx` | `clojure` | Text |\n| ClojureScript | `.cljs` | `clojurescript` | Text |\n| Closure Stylesheets (GSS) | `.gss` | None | Text |\n| CMake | `.cmake`, `CMakeLists.txt` | `cmake` | Text |\n| COBOL | `.cob`, `.cpy` | `cobol` | Text |\n| CoffeeScript | `.coffee` | `coffee`, `coffee-script`, `coffeescript` | Text |\n| Common Lisp | `.cl`, `.lisp`, `.el` | `lisp` | Text |\n| CQL (Cassandra) | `.cql` | `cql`, `cassandra` | Text |\n| Crystal | `.cr` | `crystal` | Text |\n| CSS | `.css` | `css` | Text |\n| Cypher | `.cyp`, `.cypher` | `cypher` | Text |\n| Cython | `.pyx`, `.pxd`, `.pxi` | `cython` | Text |\n| D | `.d` | `d` | Text |\n| Dart | `.dart` | `dart` | Text |\n| Diff | `.diff`, `.patch` | `diff` | Text |\n| Dockerfile | `Dockerfile` | `docker`, `dockerfile` | Text |\n| DTD | `.dtd` | `dtd` | Text |\n| Dylan | `.dylan`, `.dyl`, `.intr` | `dylan` | Text |\n| EBNF | None | `ebnf` | None |\n| ECL | `.ecl` | `ecl` | Text |\n| edn | `.edn` | `edn` | Text |\n| Eiffel | `.e` | `eiffel` | Text |\n| Elm | `.elm` | `elm` | Text |\n| Erlang | `.erl` | `erlang` | Text |\n| Esper | None | `esper` | None |\n| F# | `.fs` | `fsharp`, `f#` | Text |\n| Factor | `.factor` | `factor` | Text |\n| FCL | None | `fcl` | None |\n| Forth | `.forth`, `.fth`, `.4th` | `forth` | Text |\n| Fortran | `.f`, `.for`, `.f77`, `.f90`, `.f95` | `fortran` | Text |\n| Gas (GNU assembler) | `.s` | `gas` | Text |\n| Gherkin | `.feature` | `gherkin` | Text |\n| Go | `.go` | `go` | Text |\n| Groovy | `.groovy`, `.gradle`, `Jenkinsfile` | `groovy` | Text |\n| Haskell | `.hs` | `haskell` | Text |\n| Haxe | `.hx` | `haxe` | Text |\n| HTML | `.html`, `.htm`, `.handlebars`, `.hbs` | `html`, `htm`, `xhtml` | Text |\n| HTTP | None | `http` | None |\n| HXML | `.hxml` | `hxml` | Text |\n| IDL | `.pro` | `idl` | Text |\n| Java | `.java` | `java` | Text |\n| JavaScript | `.js`, `.mjs`, `.cjs` | `js`, `javascript`, `ecmascript`, `node` | Text |\n| Jinja | `.j2`, `.jinja`, `.jinja2` | `jinja` | Text |\n| JSON | `.json`, `.map` | `json`, `json5` | Text |\n| JSON-LD | `.jsonld` | `jsonld`, `json-ld` | Text |\n| JSX | `.jsx` | `jsx` | Text |\n| Julia | `.jl` | `julia` | Text |\n| Kotlin | `.kt`, `.kts` | `kt`, `kotlin` | Text |\n| LaTeX | `.text`, `.ltx`, `.tex` | `tex`, `latex` | Text |\n| LESS | `.less` | `less` | Text |\n| Liquid | `.liquid` | `liquid` | Text |\n| LiveScript | `.ls` | `ls`, `livescript` | Text |\n| Lua | `.lua` | `lua` | Text |\n| MariaDB SQL | None | `mariadb` | None |\n| Markdown | `.md`, `.markdown` | `md`, `markdown` | Markdown |\n| Markdown source | `.mkd` | `md`, `markdown` | Text |\n| Mathematica | `.m`, `.nb`, `.wl`, `.wls` | `mathematica` | Text |\n| Mbox | `.mbox` | `mbox` | Text |\n| mIRC | `.mrc` | `mirc` | Text |\n| Modelica | `.mo` | `modelica` | Text |\n| MS SQL | None | `mssql` | None |\n| MscGen | `.mscgen`, `.mscin`, `.msc` | `mscgen` | Text |\n| MsGenny | `.msgenny` | `msgenny` | Text |\n| MUMPS | `.mps` | `mumps` | Text |\n| MySQL | None | `mysql` | None |\n| Nginx | Names ending in `.conf` that contain `nginx`, such as `nginx.conf` | `nginx` | Text |\n| NSIS | `.nsh`, `.nsi` | `nsis` | Text |\n| NTriples | `.nt`, `.nq` | `ntriples` | Text |\n| Objective-C | None | `objective-c`, `objc` | None |\n| Objective-C++ | `.mm` | `objective-c++`, `objc++` | Text |\n| OCaml | `.ml`, `.mli`, `.mll`, `.mly` | `ocaml` | Text |\n| Octave | None | `octave` | None |\n| Oz | `.oz` | `oz` | Text |\n| Pascal | `.p`, `.pas` | `pascal` | Text |\n| Perl | `.pl`, `.pm` | `perl` | Text |\n| PGP | `.asc`, `.pgp`, `.sig` | `pgp`, `asciiarmor` | Text |\n| PHP | `.php`, `.php3`, `.php4`, `.php5`, `.php7`, `.phtml` | `php` | Text |\n| Pig | `.pig` | `pig` | Text |\n| Plain text (no highlighting) | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | `text`, `txt`, `plaintext`, `plain`, `none` | Text |\n| PLSQL | `.pls` | `plsql` | Text |\n| PostgreSQL | None | `postgresql` | None |\n| PowerShell | `.ps1`, `.psd1`, `.psm1` | `ps1`, `powershell` | Text |\n| Properties files | `.properties`, `.ini`, `.in` | `ini`, `properties` | Text |\n| ProtoBuf | `.proto` | `protobuf` | Text |\n| Pug | `.pug`, `.jade` | `jade`, `pug` | Text |\n| Puppet | `.pp` | `puppet` | Text |\n| Python | `.build`, `.bzl`, `.py`, `.pyw`, `BUCK`, `BUILD` | `py`, `python` | Text |\n| Q | `.q` | `q` | Text |\n| R | `.r` | `r`, `rscript` | Text |\n| RPM Spec | `.spec` | None | Text |\n| Ruby | `.rb`, `Gemfile`, `Rakefile` | `rb`, `ruby`, `jruby`, `macruby`, `rake`, `rbx` | Text |\n| Rust | `.rs` | `rs`, `rust` | Text |\n| SAS | `.sas` | `sas` | Text |\n| Sass | `.sass` | `sass` | Text |\n| Scala | `.scala` | `scala` | Text |\n| Scheme | `.scm`, `.ss` | `scheme` | Text |\n| SCSS | `.scss` | `scss` | Text |\n| Shell | `.sh`, `.ksh`, `.bash`, `PKGBUILD` | `sh`, `bash`, `zsh`, `shell`, `shellsession`, `console` | Text |\n| Sieve | `.siv`, `.sieve` | `sieve` | Text |\n| Smalltalk | `.st` | `smalltalk` | Text |\n| SML | `.sml`, `.fun`, `.smackspec` | `sml` | Text |\n| Solr | None | `solr` | None |\n| SPARQL | `.rq`, `.sparql` | `sparql`, `sparul` | Text |\n| Spreadsheet | None | `excel`, `formula`, `spreadsheet` | None |\n| SQL | `.sql` | `sql` | Text |\n| SQLite | None | `sqlite` | None |\n| Squirrel | `.nut` | `squirrel` | Text |\n| sTeX | None | `stex` | None |\n| Stylus | `.styl` | `stylus` | Text |\n| SVG (XML highlighting) | `.svg` | `xml`, `rss`, `wsdl`, `xsd` | Image |\n| Swift | `.swift` | `swift` | Text |\n| SystemVerilog | `.v`, `.sv`, `.svh` | `systemverilog` | Text |\n| Tcl | `.tcl` | `tcl` | Text |\n| Textile | `.textile` | `textile` | Text |\n| TiddlyWiki | None | `tiddlywiki` | None |\n| TOML | `.toml` | `toml` | Text |\n| Troff | `.1`, `.2`, `.3`, `.4`, `.5`, `.6`, `.7`, `.8`, `.9` | `troff` | Text |\n| TSX | `.tsx` | `tsx` | Text |\n| TTCN | `.ttcn`, `.ttcn3`, `.ttcnpp` | `ttcn` | Text |\n| TTCN_CFG | `.cfg` | `ttcn_cfg` | Text |\n| Turtle | `.ttl` | `turtle` | Text |\n| TypeScript | `.ts`, `.mts`, `.cts` | `ts`, `typescript` | Text |\n| VB.NET | `.vb` | `vb.net` | Text |\n| VBScript | `.vbs` | `vbscript` | Text |\n| Velocity | `.vtl` | `velocity` | Text |\n| Verilog | None | `verilog` | None |\n| VHDL | `.vhd`, `.vhdl` | `vhdl` | Text |\n| Vue | `.vue` | `vue` | Text |\n| Web IDL | `.webidl` | None | Text |\n| WebAssembly | `.wat`, `.wast` | `webassembly` | Text |\n| XML | `.xml`, `.xsl`, `.xsd` | `xml`, `rss`, `wsdl`, `xsd` | Text |\n| XQuery | `.xy`, `.xquery`, `.xq`, `.xqm`, `.xqy` | `xquery` | Text |\n| X\u00f9 | `.xu` | `x\u00f9` | Text |\n| Yacas | `.ys` | `yacas` | Text |\n| YAML | `.yaml`, `.yml` | `yaml`, `yml` | Text |\n| Z80 | `.z80` | `z80` | Text |\n\n## Related Guides\n\n- [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/)\n- [Edit Markdown](../../view-and-edit-files/edit-markdown/)\n- [Supported File Formats](../supported-file-formats/)\n"}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/account-and-preferences", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "account-and-preferences", "title": "Account and Preferences", "path": "user-guide/account-and-preferences", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/account-and-preferences/manage-your-account", "parent_id": "section:user-guide/account-and-preferences", "depth": 2, "kind": "page", "label": "manage-your-account", "title": "Manage Your Account", "path": "user-guide/account-and-preferences/manage-your-account", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 10, "diff_removed": 0}}, "content_versions": {"0.9": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "1.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "2.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign In With A Local Password\n\nUsernames aren't case-sensitive: `Testuser` and `testuser` sign in to the same account. Leading and trailing username whitespace is ignored. Passwords remain case-sensitive and aren't trimmed.\n\nIf an older installation already contains accounts whose usernames differ only by case, those accounts temporarily require their exact username spelling. Ask an administrator to resolve the conflicting names. Once the conflict is resolved, capitalization no longer matters.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\nAfter you sign out, your next sign-in in that tab opens the main file browser. Sambee does not save that tab's previous page for the next sign-in.\n\nIf an OIDC session expires or is revoked, signing in again returns affected tabs to their previous pages. Other open tabs recover automatically, or when you bring them into view.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "1.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "2.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign In With A Local Password\n\nUsernames aren't case-sensitive: `Testuser` and `testuser` sign in to the same account. Leading and trailing username whitespace is ignored. Passwords remain case-sensitive and aren't trimmed.\n\nIf an older installation already contains accounts whose usernames differ only by case, those accounts temporarily require their exact username spelling. Ask an administrator to resolve the conflicting names. Once the conflict is resolved, capitalization no longer matters.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\nAfter you sign out, your next sign-in in that tab opens the main file browser. Sambee does not save that tab's previous page for the next sign-in.\n\nIf an OIDC session expires or is revoked, signing in again returns affected tabs to their previous pages. Other open tabs recover automatically, or when you bring them into view.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/account-and-preferences/file-browser-preferences", "parent_id": "section:user-guide/account-and-preferences", "depth": 2, "kind": "page", "label": "file-browser-preferences", "title": "File Browser Preferences", "path": "user-guide/account-and-preferences/file-browser-preferences", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"1.0": "+++\ntitle = \"File Browser Preferences\"\n+++\n\nThese **Settings \u003e File Browser** options apply to your browser preferences, not server policy.\n\n## File Selection\n\n**Automatic** enables touch selection on larger devices with a coarse primary pointer, such as a tablet. **Always on** enables it on all larger layouts; **Off** disables it there. Phone layouts always provide touch selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\n## Shortcut Hints\n\n**Auto** shows hints on larger layouts and after keyboard use in the current compact-layout session. **Always** shows them in all layouts; **Never** hides shortcut labels without hiding Quick Bar status.\n\n## Clear Personal History\n\nClear file history under **File Search** or directory history under **Directory Navigation**. This removes history records, not files or folders. History is private to your account. Server retention and exclusions are [administrator policy](../../../admin-guide/reference/configuration-file-reference/#file-search-and-history-policy).\n", "2.0": "+++\ntitle = \"File Browser Preferences\"\n+++\n\nThese **Settings \u003e File Browser** options apply to your browser preferences, not server policy.\n\n## File Selection\n\n**Automatic** enables touch selection on larger devices with a coarse primary pointer, such as a tablet. **Always on** enables it on all larger layouts; **Off** disables it there. Phone layouts always provide touch selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\n## Shortcut Hints\n\n**Auto** shows hints on larger layouts and after keyboard use in the current compact-layout session. **Always** shows them in all layouts; **Never** hides shortcut labels without hiding Quick Bar status.\n\n## Clear Personal History\n\nClear file history under **File Search** or directory history under **Directory Navigation**. This removes history records, not files or folders. History is private to your account. Server retention and exclusions are [administrator policy](../../../admin-guide/reference/configuration-file-reference/#file-search-and-history-policy).\n"}, "page_contents": {"1.0": "+++\ntitle = \"File Browser Preferences\"\n+++\n\nThese **Settings \u003e File Browser** options apply to your browser preferences, not server policy.\n\n## File Selection\n\n**Automatic** enables touch selection on larger devices with a coarse primary pointer, such as a tablet. **Always on** enables it on all larger layouts; **Off** disables it there. Phone layouts always provide touch selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\n## Shortcut Hints\n\n**Auto** shows hints on larger layouts and after keyboard use in the current compact-layout session. **Always** shows them in all layouts; **Never** hides shortcut labels without hiding Quick Bar status.\n\n## Clear Personal History\n\nClear file history under **File Search** or directory history under **Directory Navigation**. This removes history records, not files or folders. History is private to your account. Server retention and exclusions are [administrator policy](../../../admin-guide/reference/configuration-file-reference/#file-search-and-history-policy).\n", "2.0": "+++\ntitle = \"File Browser Preferences\"\n+++\n\nThese **Settings \u003e File Browser** options apply to your browser preferences, not server policy.\n\n## File Selection\n\n**Automatic** enables touch selection on larger devices with a coarse primary pointer, such as a tablet. **Always on** enables it on all larger layouts; **Off** disables it there. Phone layouts always provide touch selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\n## Shortcut Hints\n\n**Auto** shows hints on larger layouts and after keyboard use in the current compact-layout session. **Always** shows them in all layouts; **Never** hides shortcut labels without hiding Quick Bar status.\n\n## Clear Personal History\n\nClear file history under **File Search** or directory history under **Directory Navigation**. This removes history records, not files or folders. History is private to your account. Server retention and exclusions are [administrator policy](../../../admin-guide/reference/configuration-file-reference/#file-search-and-history-policy).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:admin-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "admin-guide", "title": "Admin Guide", "path": "admin-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 1, "diff_removed": 3}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Configuration](./configuration/configuration-key-reference/): Review the config keys admins most often change and follow the related path and persistence references.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.8": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Configuration](./configuration/configuration-key-reference/): Review the config keys admins most often change and follow the related path and persistence references.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.9": "+++\ntitle = \"Admin Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "1.0": "+++\ntitle = \"Admin Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "2.0": "+++\ntitle = \"Admin Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/overview-and-planning", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "overview-and-planning", "title": "Overview and Planning", "path": "admin-guide/overview-and-planning", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/overview-and-planning/architecture-overview", "parent_id": "section:admin-guide/overview-and-planning", "depth": 2, "kind": "page", "label": "architecture-overview", "title": "Architecture Overview", "path": "admin-guide/overview-and-planning/architecture-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.8": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.9": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "1.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "2.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.8": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.9": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "1.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "2.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/installation-and-deployment", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "installation-and-deployment", "title": "Installation and Deployment", "path": "admin-guide/installation-and-deployment", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/installation-and-deployment/deploy-sambee-with-docker", "parent_id": "section:admin-guide/installation-and-deployment", "depth": 2, "kind": "page", "label": "deploy-sambee-with-docker", "title": "Deploy Sambee With Docker", "path": "admin-guide/installation-and-deployment/deploy-sambee-with-docker", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 1, "diff_removed": 8}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 1, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.8": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.9": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "1.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "2.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/sambee-app/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.8": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.9": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "1.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "2.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/sambee-app/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/installation-and-deployment/first-startup-and-first-admin-login", "parent_id": "section:admin-guide/installation-and-deployment", "depth": 2, "kind": "page", "label": "first-startup-and-first-admin-login", "title": "First Startup And First Admin Login", "path": "admin-guide/installation-and-deployment/first-startup-and-first-admin-login", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.8": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.9": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "1.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "2.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n"}, "page_contents": {"0.7": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.8": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.9": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "1.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "2.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/network-and-reverse-proxy", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "network-and-reverse-proxy", "title": "Network and Reverse Proxy", "path": "admin-guide/network-and-reverse-proxy", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy", "parent_id": "section:admin-guide/network-and-reverse-proxy", "depth": 2, "kind": "page", "label": "put-sambee-behind-a-reverse-proxy", "title": "Put Sambee Behind A Reverse Proxy", "path": "admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.8": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.9": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "1.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "2.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.8": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.9": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "1.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "2.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/network-and-reverse-proxy/network-settings", "parent_id": "section:admin-guide/network-and-reverse-proxy", "depth": 2, "kind": "page", "label": "network-settings", "title": "Network Settings", "path": "admin-guide/network-and-reverse-proxy/network-settings", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "1.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "2.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "1.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "2.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/configuration", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "configuration", "title": "Configuration", "path": "admin-guide/configuration", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/configuration/configuration-key-reference", "parent_id": "section:admin-guide/configuration", "depth": 2, "kind": "page", "label": "configuration-key-reference", "title": "Configuration Key Reference", "path": "admin-guide/configuration/configuration-key-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {"0.7": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "0.8": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "0.8": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/operations-and-maintenance", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "operations-and-maintenance", "title": "Operations and Maintenance", "path": "admin-guide/operations-and-maintenance", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/view-logs-and-restart-services", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "view-logs-and-restart-services", "title": "View Logs And Restart Services", "path": "admin-guide/operations-and-maintenance/view-logs-and-restart-services", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.8": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.9": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "1.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "2.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n"}, "page_contents": {"0.7": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.8": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.9": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "1.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "2.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/update-sambee-safely", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "update-sambee-safely", "title": "Update Sambee Safely", "path": "admin-guide/operations-and-maintenance/update-sambee-safely", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 24, "diff_removed": 0}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.8": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.9": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "1.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.", "2.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding."}, "page_contents": {"0.7": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.8": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.9": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "1.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.", "2.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/backup-and-restore-planning", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "backup-and-restore-planning", "title": "Backup And Restore Planning", "path": "admin-guide/operations-and-maintenance/backup-and-restore-planning", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.8": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.9": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "1.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "2.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.8": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.9": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "1.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "2.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/manage-directory-search", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "manage-directory-search", "title": "Manage Directory Search", "path": "admin-guide/operations-and-maintenance/manage-directory-search", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "authored"}}, "content_versions": {"2.0": "+++\ntitle = \"Manage Directory Search\"\n+++\n\nUse **Admin \u003e Directory Search** to set resource limits for backend and Companion directory indexes. Backend changes take effect on live sources. Paired browsers deliver saved Companion policy automatically while an authenticated session is active.\n\n## Resource Controls\n\nThe settings include storage, retention, cache, and verification controls, with help and allowed ranges beside each field. Start with the defaults and adjust them for the server or device capacity.\n\nThe disk budget and cache target are not hard disk or process-memory limits. Leave extra free space for background work. Lowering the budget can pause index growth; it does not trim active indexes.\n\n## Companion Policy Delivery\n\nPairing authorizes settings delivery. The most recently paired server manages Companion settings. Pairing that server again also selects it as authority. Other paired servers keep their file-access pairing but cannot replace managed settings.\n\nAll active, authenticated users can deliver the saved canonical policy. Only administrators can edit it. There is no separate policy approval or Apply action.\n\n**Settings \u003e Local Drives** shows the settings authority and separate synchronization states for directory policy, theme, and localization. Checks run after pairing, login, reconnect, persisted changes, and periodically while a tab is visible. A theme or localization change does not revise or reapply unchanged directory policy.\n\nThe device must reach the Sambee backend directly over HTTPS with a valid certificate. Redirects are not supported. HTTP is allowed only for loopback development origins.\n\n## Troubleshooting\n\nIf delivery fails, Companion keeps the last valid value for each section, or built-in defaults before the first delivery. Directory search remains available. Follow the displayed recovery action and use **Retry**. Update both applications when status reports an incompatible settings protocol.\n\nTo change authority, pair the intended server again. Unpairing the authoritative origin clears authority and keeps the last valid settings; Companion does not select another paired server automatically. For older installations with several pairings and no usable policy binding, pair the intended server again to establish authority.\n\nIf index growth pauses, restore free disk space or increase the relevant disk budget.\n\nIndexes are reused after a restart. Retained results remain unverified until background verification completes. A temporary disconnection keeps the index; restore source access to resume work.\n\n### SMB Verification and Recovery\n\nThe backend waits up to 10 seconds for directory notifications before its first source check and scan. If notification setup fails or times out, verification starts without monitoring and watcher retries continue. If monitoring becomes ready later, verification safely retries reads made before that transition. No cache reset is needed.\n\nRetained results become searchable after a valid source-root check, even while full verification continues. An unavailable root temporarily blocks search without deleting the index. Restore the source connection or permissions and let background recovery continue.\n\nDirectory changes normally retry only affected parents. Completed quiet branches remain available, and background work gives both existing results and full verification time to progress. A parent that changes during its read is deferred for at least one second. A full pass may remain incomplete while directories keep changing. To confirm complete coverage, allow a quiet period and check the verification time.\n\nA denied folder, unsafe directory, or unsupported name does not stop verification of readable folders. A completed pass can have partial coverage and a verification time. It does not mean that every folder was read. Failed folders are checked at the next regular verification. Restore their permissions or correct unsupported names to improve coverage. A failed incremental read keeps stored descendants until a later check can confirm a change.\n\nStatus messages show active conditions. A local retry alone does not mean that the source is unavailable. Follow a displayed storage, access, or monitoring recovery action. Retry delays account for both scan gates and watcher retries; a longer failure backoff can delay scan work beyond the one-second change retry. Repeated searches and status checks do not shorten that delay.\n\n### Source Boundaries\n\nSMB indexing stays within the configured share and folder. Storage mounted inside that share is included unless it is exposed through a redirect or reparse point. Local indexing does not cross mount boundaries.\n\nLocal fixed drives use a separate index when the volume serial or file-system UUID changes. Removable and unknown drives also start a new generation when the volume label, file-system type, or total capacity changes. Each volume at the same path can reuse its own retained index. Missing media pauses search without deleting the index. On Linux, mount the volume again; the empty mount-point folder is not a replacement source.\n\nFor supported platforms and database precautions, see [Directory-Search Databases](../../reference/companion-support-reference/#directory-search-databases). For backend storage configuration, see [Configuration File Reference](../../reference/configuration-file-reference/#directory-index-policy).\n"}, "page_contents": {"2.0": "+++\ntitle = \"Manage Directory Search\"\n+++\n\nUse **Admin \u003e Directory Search** to set resource limits for backend and Companion directory indexes. Backend changes take effect on live sources. Paired browsers deliver saved Companion policy automatically while an authenticated session is active.\n\n## Resource Controls\n\nThe settings include storage, retention, cache, and verification controls, with help and allowed ranges beside each field. Start with the defaults and adjust them for the server or device capacity.\n\nThe disk budget and cache target are not hard disk or process-memory limits. Leave extra free space for background work. Lowering the budget can pause index growth; it does not trim active indexes.\n\n## Companion Policy Delivery\n\nPairing authorizes settings delivery. The most recently paired server manages Companion settings. Pairing that server again also selects it as authority. Other paired servers keep their file-access pairing but cannot replace managed settings.\n\nAll active, authenticated users can deliver the saved canonical policy. Only administrators can edit it. There is no separate policy approval or Apply action.\n\n**Settings \u003e Local Drives** shows the settings authority and separate synchronization states for directory policy, theme, and localization. Checks run after pairing, login, reconnect, persisted changes, and periodically while a tab is visible. A theme or localization change does not revise or reapply unchanged directory policy.\n\nThe device must reach the Sambee backend directly over HTTPS with a valid certificate. Redirects are not supported. HTTP is allowed only for loopback development origins.\n\n## Troubleshooting\n\nIf delivery fails, Companion keeps the last valid value for each section, or built-in defaults before the first delivery. Directory search remains available. Follow the displayed recovery action and use **Retry**. Update both applications when status reports an incompatible settings protocol.\n\nTo change authority, pair the intended server again. Unpairing the authoritative origin clears authority and keeps the last valid settings; Companion does not select another paired server automatically. For older installations with several pairings and no usable policy binding, pair the intended server again to establish authority.\n\nIf index growth pauses, restore free disk space or increase the relevant disk budget.\n\nIndexes are reused after a restart. Retained results remain unverified until background verification completes. A temporary disconnection keeps the index; restore source access to resume work.\n\n### SMB Verification and Recovery\n\nThe backend waits up to 10 seconds for directory notifications before its first source check and scan. If notification setup fails or times out, verification starts without monitoring and watcher retries continue. If monitoring becomes ready later, verification safely retries reads made before that transition. No cache reset is needed.\n\nRetained results become searchable after a valid source-root check, even while full verification continues. An unavailable root temporarily blocks search without deleting the index. Restore the source connection or permissions and let background recovery continue.\n\nDirectory changes normally retry only affected parents. Completed quiet branches remain available, and background work gives both existing results and full verification time to progress. A parent that changes during its read is deferred for at least one second. A full pass may remain incomplete while directories keep changing. To confirm complete coverage, allow a quiet period and check the verification time.\n\nA denied folder, unsafe directory, or unsupported name does not stop verification of readable folders. A completed pass can have partial coverage and a verification time. It does not mean that every folder was read. Failed folders are checked at the next regular verification. Restore their permissions or correct unsupported names to improve coverage. A failed incremental read keeps stored descendants until a later check can confirm a change.\n\nStatus messages show active conditions. A local retry alone does not mean that the source is unavailable. Follow a displayed storage, access, or monitoring recovery action. Retry delays account for both scan gates and watcher retries; a longer failure backoff can delay scan work beyond the one-second change retry. Repeated searches and status checks do not shorten that delay.\n\n### Source Boundaries\n\nSMB indexing stays within the configured share and folder. Storage mounted inside that share is included unless it is exposed through a redirect or reparse point. Local indexing does not cross mount boundaries.\n\nLocal fixed drives use a separate index when the volume serial or file-system UUID changes. Removable and unknown drives also start a new generation when the volume label, file-system type, or total capacity changes. Each volume at the same path can reuse its own retained index. Missing media pauses search without deleting the index. On Linux, mount the volume again; the empty mount-point folder is not a replacement source.\n\nFor supported platforms and database precautions, see [Directory-Search Databases](../../reference/companion-support-reference/#directory-search-databases). For backend storage configuration, see [Configuration File Reference](../../reference/configuration-file-reference/#directory-index-policy).\n"}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/reference", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "reference", "title": "Reference", "path": "admin-guide/reference", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/reference/port-and-path-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "port-and-path-reference", "title": "Port And Path Reference", "path": "admin-guide/reference/port-and-path-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.8": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.9": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "1.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "2.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.8": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.9": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "1.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "2.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/companion-support-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "companion-support-reference", "title": "Companion Support Reference", "path": "admin-guide/reference/companion-support-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 13, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.8": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.9": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "1.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "2.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Directory-Search Databases\n\nCompanion stores its SQLite directory indexes in the current OS user's cache directory.\n\n| Platform | Location |\n|---|---|\n| Linux | `$XDG_CACHE_HOME/app.sambee.companion/directory-index/sqlite/`, or `~/.cache/app.sambee.companion/directory-index/sqlite/` when `XDG_CACHE_HOME` is not set to an absolute path |\n| Windows | `%LOCALAPPDATA%\\app.sambee.companion\\directory-index\\sqlite\\` |\n\nThese databases contain local directory paths. Keep access restricted to the device's OS user, and exit Companion before copying or removing index files. Do not edit the databases or remove individual SQLite sidecar files. macOS directory indexing is not available.\n\nSee [Manage Directory Search](../../operations-and-maintenance/manage-directory-search/) to configure resource limits and apply them to devices.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.8": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.9": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "1.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "2.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Directory-Search Databases\n\nCompanion stores its SQLite directory indexes in the current OS user's cache directory.\n\n| Platform | Location |\n|---|---|\n| Linux | `$XDG_CACHE_HOME/app.sambee.companion/directory-index/sqlite/`, or `~/.cache/app.sambee.companion/directory-index/sqlite/` when `XDG_CACHE_HOME` is not set to an absolute path |\n| Windows | `%LOCALAPPDATA%\\app.sambee.companion\\directory-index\\sqlite\\` |\n\nThese databases contain local directory paths. Keep access restricted to the device's OS user, and exit Companion before copying or removing index files. Do not edit the databases or remove individual SQLite sidecar files. macOS directory indexing is not available.\n\nSee [Manage Directory Search](../../operations-and-maintenance/manage-directory-search/) to configure resource limits and apply them to devices.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/configuration-file-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "configuration-file-reference", "title": "Configuration File Reference", "path": "admin-guide/reference/configuration-file-reference", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 8, "diff_removed": 0}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 12, "diff_removed": 4}}, "content_versions": {"0.9": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "1.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## File Search and History Policy\n\nUse **Settings \u003e File Search** for shared retention, results per group, and file-history exclusions. These are administrator settings, not personal File Browser preferences. The page identifies built-in defaults or a saved system override; administrators can reset an override.\n\nLowering retention removes the oldest history records immediately. Zero clears history and prevents new records. Image, temporary, backup, and extension exclusions apply before file history is stored. Enter one literal extension per exclusion; Sambee normalizes `TMP` to `.tmp`.\n\nUsers can clear their own file and directory histories in **Settings \u003e File Browser**. Removing history does not delete stored files or folders.\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "2.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location` | Selects the private backend directory-index root. SQLite catalogues are reused after restart and marked unverified until background verification completes. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## File Search and History Policy\n\nUse **Settings \u003e File Search** for shared retention, results per group, and file-history exclusions. These are administrator settings, not personal File Browser preferences.\n\n**Recent files and directories to retain** defaults to 200 files and 200 directories per user, with separate limits for the lists. Existing administrator overrides remain unchanged. Lowering retention immediately removes the oldest records from both lists; zero clears both lists and prevents new records. **Results per group** defaults to 10 and applies to both search modes.\n\nImage, temporary, backup, and extension exclusions apply only to file history before storage. Enter one literal extension per exclusion; Sambee normalizes `TMP` to `.tmp`.\n\nUsers can clear their own histories in **Settings \u003e File Browser**. Removing history does not delete stored files or folders.\n\n## Directory-Index Policy\n\nDirectory-index resource policies have no TOML override. Configure them in **Admin \u003e Directory Search**; see [Manage Directory Search](../../operations-and-maintenance/manage-directory-search/) for controls, Companion approval, and recovery.\n\n`directory_cache.location` selects only the backend storage root.\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "1.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## File Search and History Policy\n\nUse **Settings \u003e File Search** for shared retention, results per group, and file-history exclusions. These are administrator settings, not personal File Browser preferences. The page identifies built-in defaults or a saved system override; administrators can reset an override.\n\nLowering retention removes the oldest history records immediately. Zero clears history and prevents new records. Image, temporary, backup, and extension exclusions apply before file history is stored. Enter one literal extension per exclusion; Sambee normalizes `TMP` to `.tmp`.\n\nUsers can clear their own file and directory histories in **Settings \u003e File Browser**. Removing history does not delete stored files or folders.\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "2.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location` | Selects the private backend directory-index root. SQLite catalogues are reused after restart and marked unverified until background verification completes. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## File Search and History Policy\n\nUse **Settings \u003e File Search** for shared retention, results per group, and file-history exclusions. These are administrator settings, not personal File Browser preferences.\n\n**Recent files and directories to retain** defaults to 200 files and 200 directories per user, with separate limits for the lists. Existing administrator overrides remain unchanged. Lowering retention immediately removes the oldest records from both lists; zero clears both lists and prevents new records. **Results per group** defaults to 10 and applies to both search modes.\n\nImage, temporary, backup, and extension exclusions apply only to file history before storage. Enter one literal extension per exclusion; Sambee normalizes `TMP` to `.tmp`.\n\nUsers can clear their own histories in **Settings \u003e File Browser**. Removing history does not delete stored files or folders.\n\n## Directory-Index Policy\n\nDirectory-index resource policies have no TOML override. Configure them in **Admin \u003e Directory Search**; see [Manage Directory Search](../../operations-and-maintenance/manage-directory-search/) for controls, Companion approval, and recovery.\n\n`directory_cache.location` selects only the backend storage root.\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/smb-settings", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "smb-settings", "title": "Smb Settings", "path": "admin-guide/reference/smb-settings", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "1.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "2.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "1.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "2.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/authentication", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "authentication", "title": "Authentication", "path": "admin-guide/authentication", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/authentication/authentication-overview", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "authentication-overview", "title": "Authentication Overview", "path": "admin-guide/authentication/authentication-overview", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "1.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "2.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "1.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "2.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/password-authentication", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "password-authentication", "title": "Password Authentication", "path": "admin-guide/authentication/password-authentication", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "1.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "2.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "1.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "2.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/openid-connect-authentication-setup", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "openid-connect-authentication-setup", "title": "Openid Connect Authentication Setup", "path": "admin-guide/authentication/openid-connect-authentication-setup", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 23, "diff_removed": 7}}, "content_versions": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- Scopes:\n   - `openid`: required\n   - `profile`: often necessary for the provider to return `preferred_username`, which Sambee requires\n   - `email`: optional\n   - `groups`: required when using group admission or group-based role mappings\n   - `offline_access`: may be required for refresh tokens, depending on the provider\n- Authorization code grant\n- Refresh token grant: optional\n\n#### Token Lifetimes\n\nConfigure token lifetimes:\n\n- Refresh token, if the provider issues one:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n#### Refresh Tokens\n\nHaving the provider issue refresh tokens is recommended as that enables background session renewal without user interaction.\n\nProviders that don't issue refresh tokens can still be used with Sambee. They must return an ID token with a valid `auth_time` claim when Sambee requests `max_age`.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid` and every scope required for the configured claims, such as `profile` and `email`. Add `groups` for group admission or group-based role mappings. Add `offline_access` only if supported and needed for provider refresh tokens. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control the maximum age of a verified IdP sign-in. The default is 30 days.\n\nSet **Session limit without refresh token (hours)** separately for sign-ins that return no refresh token (default 8 hours; allowed range 1-24 hours).\n\nSambee issues short-lived API tokens (up to 60 minutes) while the browser session remains valid. With a refresh token, Sambee can renew through the IdP until the authentication-age limit. Without one, Sambee can issue another API token from the browser cookie only until the fixed session limit. Reducing that limit shortens existing no-refresh sessions; increasing it does not extend them. When the applicable deadline arrives, Sambee starts a new top-level IdP authorization, which might reuse the IdP's existing SSO session.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n- **Session renewal** reports whether this particular test returned a refresh token. A test without one can still succeed; users will need to sign in again after the configured no-refresh session limit.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n"}, "page_contents": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- Scopes:\n   - `openid`: required\n   - `profile`: often necessary for the provider to return `preferred_username`, which Sambee requires\n   - `email`: optional\n   - `groups`: required when using group admission or group-based role mappings\n   - `offline_access`: may be required for refresh tokens, depending on the provider\n- Authorization code grant\n- Refresh token grant: optional\n\n#### Token Lifetimes\n\nConfigure token lifetimes:\n\n- Refresh token, if the provider issues one:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n#### Refresh Tokens\n\nHaving the provider issue refresh tokens is recommended as that enables background session renewal without user interaction.\n\nProviders that don't issue refresh tokens can still be used with Sambee. They must return an ID token with a valid `auth_time` claim when Sambee requests `max_age`.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid` and every scope required for the configured claims, such as `profile` and `email`. Add `groups` for group admission or group-based role mappings. Add `offline_access` only if supported and needed for provider refresh tokens. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control the maximum age of a verified IdP sign-in. The default is 30 days.\n\nSet **Session limit without refresh token (hours)** separately for sign-ins that return no refresh token (default 8 hours; allowed range 1-24 hours).\n\nSambee issues short-lived API tokens (up to 60 minutes) while the browser session remains valid. With a refresh token, Sambee can renew through the IdP until the authentication-age limit. Without one, Sambee can issue another API token from the browser cookie only until the fixed session limit. Reducing that limit shortens existing no-refresh sessions; increasing it does not extend them. When the applicable deadline arrives, Sambee starts a new top-level IdP authorization, which might reuse the IdP's existing SSO session.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n- **Session renewal** reports whether this particular test returned a refresh token. A test without one can still succeed; users will need to sign in again after the configured no-refresh session limit.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/openid-connect-authentication-operations", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "openid-connect-authentication-operations", "title": "Openid Connect Authentication Operations", "path": "admin-guide/authentication/openid-connect-authentication-operations", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 25, "diff_removed": 4}}, "content_versions": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nWhen a provider returns a refresh token, Sambee stores it encrypted on the server. If the provider returns none, Sambee stores no provider token. In both cases, the browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing provider tokens to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background while the session remains valid. A session with a refresh token is limited by the configured interactive sign-in interval (default 30 days from the verified IdP authentication). A session without a refresh token has a fixed limit of 8 hours from the callback by default, configurable from 1 to 24 hours. Neither local activity nor API-token renewal extends that deadline; the earlier applicable deadline always wins. Reducing the no-refresh limit permanently shortens existing sessions, including pending sign-ins.\n\nA new top-level authorization is required when the applicable deadline ends, the identity provider rejects or revokes a refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. The IdP might use its SSO cookie to return quickly, but this is not guaranteed. Sambee returns the user to the same safe route after sign-in. Registered text and Markdown drafts are snapshotted before an authentication redirect when storage is available; other unsaved work might be interrupted. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for limitations and recovery behavior.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Local Username Matching And Upgrade Conflicts\n\nLocal-password sign-in matches usernames without regard to capitalization, using Unicode case folding and ignoring leading and trailing whitespace. Stored spelling is preserved. Passwords remain case-sensitive. New accounts and renamed accounts can't introduce case-insensitive duplicates, including accounts created through OIDC.\n\nUpgrades complete automatically even if existing accounts have conflicting names, such as `UserA` and `usera`. Accounts, passwords, roles, ownership, and identity links are preserved. Each conflicting account continues to accept only its exact stored username spelling; other capitalizations are rejected without choosing an account by its password. Disabled, expired, and passwordless accounts also count toward a conflict.\n\n**Settings** \u003e **Administration** \u003e **Users** lists conflicts in a warning, regardless of directory filters or pagination. Resolve a conflict by renaming an account through its normal editor, or deleting an account that's no longer needed. Deleting an account remains subject to the normal deletion consequences and administrator safeguards. Unchanged usernames and case-only renames remain available while resolving existing conflicts. Once only one account has a comparison key, case-insensitive password sign-in applies automatically, without restarting or rerunning a migration.\n\nOIDC identity matching and automatic linking still require the exact username spelling. A case-only match doesn't automatically link an identity or create another account; resolve that collision through the existing identity-mapping controls.\n\n## Require A Local Password Change\n\nWhen creating a local user or resetting an existing local password, enable **Require change on next password sign-in** to require a new password before the user can continue. The user directory shows **Pwd change req'd** while this requirement is pending.\n\nAfter signing in with the temporary or existing local password, the user must enter that password, choose a different password, and confirm it. They can sign out instead, but can't browse files, use administration settings, or issue companion credentials until the change succeeds. Successful changes invalidate existing Sambee tokens and require another sign-in.\n\nThe requirement applies only to local-password sessions. A linked user can still sign in through OIDC; that doesn't clear the local-password requirement or change the identity provider's password. Passwordless OIDC accounts have no local password to reset. In **OIDC only** mode, local password changes are unavailable.\n\nExisting password-change flags are enforced after upgrading. They aren't cleared automatically. If a user can't complete the change, an administrator can set another local password through User Management. Switch the requirement off during that reset only when the replacement password is intended to be permanent. Authentication-disabled mode doesn't enforce the change workflow.\n\n## Audit Events\n\nOIDC configuration, identity events, and successful local password changes and resets are stored in the Sambee database. They do not contain passwords, raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\nAll capitalization and Unicode case-folding variants of a username share the same username-based password limit, including legacy conflicting accounts.\n"}, "page_contents": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nWhen a provider returns a refresh token, Sambee stores it encrypted on the server. If the provider returns none, Sambee stores no provider token. In both cases, the browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing provider tokens to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background while the session remains valid. A session with a refresh token is limited by the configured interactive sign-in interval (default 30 days from the verified IdP authentication). A session without a refresh token has a fixed limit of 8 hours from the callback by default, configurable from 1 to 24 hours. Neither local activity nor API-token renewal extends that deadline; the earlier applicable deadline always wins. Reducing the no-refresh limit permanently shortens existing sessions, including pending sign-ins.\n\nA new top-level authorization is required when the applicable deadline ends, the identity provider rejects or revokes a refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. The IdP might use its SSO cookie to return quickly, but this is not guaranteed. Sambee returns the user to the same safe route after sign-in. Registered text and Markdown drafts are snapshotted before an authentication redirect when storage is available; other unsaved work might be interrupted. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for limitations and recovery behavior.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Local Username Matching And Upgrade Conflicts\n\nLocal-password sign-in matches usernames without regard to capitalization, using Unicode case folding and ignoring leading and trailing whitespace. Stored spelling is preserved. Passwords remain case-sensitive. New accounts and renamed accounts can't introduce case-insensitive duplicates, including accounts created through OIDC.\n\nUpgrades complete automatically even if existing accounts have conflicting names, such as `UserA` and `usera`. Accounts, passwords, roles, ownership, and identity links are preserved. Each conflicting account continues to accept only its exact stored username spelling; other capitalizations are rejected without choosing an account by its password. Disabled, expired, and passwordless accounts also count toward a conflict.\n\n**Settings** \u003e **Administration** \u003e **Users** lists conflicts in a warning, regardless of directory filters or pagination. Resolve a conflict by renaming an account through its normal editor, or deleting an account that's no longer needed. Deleting an account remains subject to the normal deletion consequences and administrator safeguards. Unchanged usernames and case-only renames remain available while resolving existing conflicts. Once only one account has a comparison key, case-insensitive password sign-in applies automatically, without restarting or rerunning a migration.\n\nOIDC identity matching and automatic linking still require the exact username spelling. A case-only match doesn't automatically link an identity or create another account; resolve that collision through the existing identity-mapping controls.\n\n## Require A Local Password Change\n\nWhen creating a local user or resetting an existing local password, enable **Require change on next password sign-in** to require a new password before the user can continue. The user directory shows **Pwd change req'd** while this requirement is pending.\n\nAfter signing in with the temporary or existing local password, the user must enter that password, choose a different password, and confirm it. They can sign out instead, but can't browse files, use administration settings, or issue companion credentials until the change succeeds. Successful changes invalidate existing Sambee tokens and require another sign-in.\n\nThe requirement applies only to local-password sessions. A linked user can still sign in through OIDC; that doesn't clear the local-password requirement or change the identity provider's password. Passwordless OIDC accounts have no local password to reset. In **OIDC only** mode, local password changes are unavailable.\n\nExisting password-change flags are enforced after upgrading. They aren't cleared automatically. If a user can't complete the change, an administrator can set another local password through User Management. Switch the requirement off during that reset only when the replacement password is intended to be permanent. Authentication-disabled mode doesn't enforce the change workflow.\n\n## Audit Events\n\nOIDC configuration, identity events, and successful local password changes and resets are stored in the Sambee database. They do not contain passwords, raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\nAll capitalization and Unicode case-folding variants of a username share the same username-based password limit, including legacy conflicting accounts.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:developer-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "developer-guide", "title": "Developer Guide", "path": "developer-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Developer Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "0.8": "+++\ntitle = \"Developer Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "0.9": "+++\ntitle = \"Developer Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "1.0": "+++\ntitle = \"Developer Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "2.0": "+++\ntitle = \"Developer Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/project-orientation", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "project-orientation", "title": "Project Orientation", "path": "developer-guide/project-orientation", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "0.8": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "0.9": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "1.0": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "2.0": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/project-orientation/what-sambee-consists-of", "parent_id": "section:developer-guide/project-orientation", "depth": 2, "kind": "page", "label": "what-sambee-consists-of", "title": "What Sambee Consists Of", "path": "developer-guide/project-orientation/what-sambee-consists-of", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.8": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.9": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "1.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "2.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n"}, "page_contents": {"0.7": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.8": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.9": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "1.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "2.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/project-orientation/repository-tour", "parent_id": "section:developer-guide/project-orientation", "depth": 2, "kind": "page", "label": "repository-tour", "title": "Repository Tour", "path": "developer-guide/project-orientation/repository-tour", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.8": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.9": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "1.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "2.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.8": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.9": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "1.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "2.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/local-development-workflow", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "local-development-workflow", "title": "Local Development Workflow", "path": "developer-guide/local-development-workflow", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "0.8": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "0.9": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "1.0": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "2.0": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/local-development-workflow/set-up-the-development-environment", "parent_id": "section:developer-guide/local-development-workflow", "depth": 2, "kind": "page", "label": "set-up-the-development-environment", "title": "Set Up The Development Environment", "path": "developer-guide/local-development-workflow/set-up-the-development-environment", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 7, "diff_removed": 0}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 13, "diff_removed": 2}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "0.8": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).", "0.9": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "1.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "2.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "0.8": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).", "0.9": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "1.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "2.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/local-development-workflow/common-task-commands", "parent_id": "section:developer-guide/local-development-workflow", "depth": 2, "kind": "page", "label": "common-task-commands", "title": "Common Task Commands", "path": "developer-guide/local-development-workflow/common-task-commands", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 16, "diff_removed": 0}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.8": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.9": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "1.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "2.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.8": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.9": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "1.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "2.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/backend-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "backend-architecture", "title": "Backend Architecture", "path": "developer-guide/backend-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "0.8": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "0.9": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "1.0": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "2.0": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/backend-overview", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "backend-overview", "title": "Backend Overview", "path": "developer-guide/backend-architecture/backend-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.8": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.9": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "1.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "2.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.8": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.9": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "1.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "2.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/request-flow-and-service-boundaries", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "request-flow-and-service-boundaries", "title": "Request Flow And Service Boundaries", "path": "developer-guide/backend-architecture/request-flow-and-service-boundaries", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.8": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.9": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "1.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "2.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.8": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.9": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "1.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "2.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/image-preprocessing-and-conversion-pipeline", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "image-preprocessing-and-conversion-pipeline", "title": "Image Preprocessing And Conversion Pipeline", "path": "developer-guide/backend-architecture/image-preprocessing-and-conversion-pipeline", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/smb-change-notification-and-directory-freshness", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "smb-change-notification-and-directory-freshness", "title": "Smb Change Notification And Directory Freshness", "path": "developer-guide/backend-architecture/smb-change-notification-and-directory-freshness", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 236, "diff_removed": 199}}, "content_versions": {"0.7": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses two separate SMB2/SMB3 `CHANGE_NOTIFY` paths: one tells an open browser to refresh its directory listing; the other maintains the directory-search index. They have different subscription, event, and consistency rules.\n\n## Components\n\n| Component | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | Browser subscriptions, access checks, path-prefix mapping, and `directory_changed` delivery |\n| `backend/app/services/directory_monitor.py` | Shared per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | Per-connection index lifecycle, recursive directory-name notifications, and background verification |\n| `backend/app/services/directory_index.py` | SQLite storage, generations, search, and maintenance |\n| `backend/app/services/directory_traversal.py` | Handle-bound SMB enumeration, identity validation, and exact missing-child checks |\n| `companion/src-tauri/src/server/directory_manager.rs` | Local-drive index lifecycle, native observations, and background workers |\n| `backend/app/main.py` | Backend monitor and cache shutdown |\n\n## Browser Notifications\n\n### Subscriptions and Paths\n\n`DirectoryMonitor` shares one `MonitoredDirectory` per `connection_id:path`. The first subscriber starts it; the last unsubscribe stops it. A WebSocket disconnect must release that client's subscriptions.\n\nThe WebSocket layer uses user-facing paths. `ConnectionManager` applies the connection's `path_prefix` to obtain the native SMB path. Notification callbacks map that path back to the user-facing path before delivery. Subscription keys and native watch paths must not be used interchangeably.\n\n| Message | Example |\n|---|---|\n| Subscribe | `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n| Unsubscribe | `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n| Change notification | `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n\n### Events and Refreshes\n\nBrowser watchers observe file names, directory names, sizes, and last-write changes in the subscribed directory's immediate children. They do not watch the whole subtree. A deep write does not invalidate every ancestor listing, although metadata changes reported for an immediate child directory can trigger a refresh.\n\nThe browser retains loaded rows during automatic refresh, including an empty listing. It waits for an active listing request, combines notifications into one pending refresh, and starts at most one automatic refresh per second. Navigation and pane disposal cancel queued refreshes.\n\n`directory_changed` requests a new listing; it is not a file-difference protocol. See [File Browser and Navigation Model](../../frontend-architecture/file-browser-and-navigation-model/) for browser state and request handling.\n\n### Resource Ownership\n\nA monitor acquires its connection, session, tree, directory handle, and `FileSystemWatcher` in that order. Cleanup runs in reverse order, including after partial initialization.\n\nCancellation during startup retains the pending worker. When startup finishes, cleanup releases only the subscription acquired by that worker, not a replacement subscription. Shutdown rejects new monitor startup.\n\nTransient failures use capped exponential reconnect backoff with jitter. Recovery continues after fast retries are exhausted, while the subscription remains active. Deletion of the watched directory stops its monitor. A stopped monitor is not reused for new subscribers. Shutdown calls `shutdown_monitor()`; a worker that is still running retains its handles until it exits.\n\n## Directory-Index Consistency\n\nThe backend and companion maintain SQLite directory indexes through shared background managers, not per-request tree walks. Cold queries return status while initialization proceeds. Committed initial batches are searchable with partial coverage; result limits do not limit indexed coverage or exact match counts.\n\nThe index watcher observes directory-name changes recursively from the share root or configured prefix. Events drive parent reconciliation. Periodic full verification covers missed notifications; it must not become a full rescan on every navigation or query.\n\n### Generations and Observation Order\n\nFull verification updates the selected generation in place while retained data remains searchable. Interrupted first builds and active verification passes keep their rows, pass identity, and queued parents, including item issues and storage reopens. A completed full pass advances `last_verified_at_ms` even with item issues; incremental changes and queries do not. Each index retains one generation, with `building` for an initial build and `accepted` after completion.\n\nNon-root access failures, unsafe traversal, invalid names, and other item read errors do not stop a pass. The scanner skips an invalid name or completes a failed parent, then continues with readable siblings. A failed parent retains stored descendants, including batches already published during the current read. Acceptance retains the issue count and sets partial coverage. It clears the verification request and uses the regular verification interval, not a special item retry. Event loss still blocks acceptance and keeps coverage uncertain. Root, transport, authentication, resource-limit, and storage failures retain their retry and recovery rules.\n\nRead tokens and observation barriers reject stale results. Observed directory changes update the index and request verification, but they do not change coverage. Lost events or pending-observation queue overflow mark coverage uncertain and request verification without deleting retained data. Pass acceptance requires a valid root and no outstanding observations or reads that could invalidate the pass.\n\nDirectory rows, FTS entries, counts, issues, queued subtree work, and revision updates must remain transactionally consistent. Queries read results and metadata from one selected-generation transaction.\n\n### SMB Watcher Startup\n\nBackend initialization waits up to 10 seconds for the first watcher attempt before it probes the source root or scans directories. Success means that the first `CHANGE_NOTIFY` request has been sent and startup invalidation has completed, not just that the thread or connection has started. The wait is asynchronous and holds no scan slot, worker, coordinator lock, or generation lock.\n\nA connection failure, notification-start failure, or timeout permits fallback verification. Watcher retries continue in the background. A failed first attempt reports unavailable monitoring, not lost observations before monitoring started. The first-attempt result is separate from current monitoring readiness. Cancellation and shutdown remove the waiter and prevent a later scan from starting.\n\nIf the watcher first becomes ready during fallback verification, it changes the epoch. Pre-monitoring reads cannot commit. Verification resumes after the bounded observation retry; a valid root probe keeps retained results searchable. Normal successful startup captures its scan epoch after watcher setup and needs no startup retry.\n\n### SMB Barriers and Local Retries\n\nThe backend captures an epoch for each full pass without registering a pass-wide reader. A directory read depends on that directory, its direct children, and its ancestors. A barrier on a deeper descendant does not reject the ancestor listing. A root barrier rejects all content reads. Source-root availability probes check epoch and reader ownership, not directory-content barriers.\n\nObservations update the selected generation before their barriers retire. Barriers remain only while pending observations or older live parent reads need them. When retained barriers exceed their count or byte bound, they collapse to one current root barrier. Live content reads become stale, but the epoch does not change and pending hints remain available.\n\nA stale parent stays pending and moves to the queue tail in one transaction. Published child batches remain; deferral clears their staged snapshot names. The next read re-enumerates the parent and starts a fresh snapshot. Local stale reads, final-capture refusals, and transient parent errors do not invalidate unrelated completed work. Observation loss and exhausted read capacity cause bounded revalidation of retained completed parents. Other epoch changes do not restart completed parents.\n\nThe periodic loop checks due verification before incremental reconciliation. A full pass owns the selected generation's scan queue; separate reconciliation does not run during that pass. Completed buffered ancestors commit before descendants are selected, so deleted rows and refreshed FileIds take effect first. Stale reads use the one-second observation retry; source-wide failures keep the failure backoff. Quiet branches can progress, but a full pass cannot be guaranteed to finish while relevant directories keep changing.\n\nLarge reads store early snapshot names in `scan_snapshot_children`, owned by the pending parent queue row. This keeps memory bounded without separate per-child absence requests. The final diff considers both staged names and the final child batch. Direct-child changes still reject the read before parent completion. Failed parent reads preserve stored children instead of applying an incomplete deletion diff.\n\n### Parent Reconciliation\n\nBackground workers reconcile affected parents between full passes. Renames check both parents, and new directories trigger descendant reads. A completed listing under a held, validated parent drives the atomic child diff; an incomplete listing or access error cannot delete missing children. Streamed reads use the same disk-backed snapshot names as full passes. An item error records partial coverage, completes the parent, and retains its stored subtree. Source-wide failures and stale observations leave work pending. Reconciliation does not establish full verification or clear uncertain coverage.\n\nFile operations queue parent hints before dispatch and after actual worker completion, including failure. New mutation paths must preserve this rule. Cancellation must not release worker ownership early or change the original operation result when hint delivery fails.\n\n### Source Identity and Traversal\n\nCatalogue names are SHA-256 hashes of source boundary settings. SMB uses the connection ID, host, port, share, configured folder, and username. Passwords, display names, connection edit times, and runtime session IDs do not change the file name. Local sources use the configured root path and, for fixed, removable, and unknown drives, available volume serial or file-system UUID evidence. Network and virtual drives use the root path alone. Runtime session IDs remain diagnostic values.\n\nReused rows are unverified until a verification pass completes. An SMB reconnect binds new handles and invalidates unfinished reads. Queued child FileIds are expected read identities, not proof of storage continuity. SMB server GUIDs and volume metadata are diagnostic values. File IDs of zero or all ones are unavailable and are not queued as expected identities. Session and tree IDs are compared only within one connection.\n\n| Source | Traversal rules |\n|---|---|\n| SMB | No automatic DFS or symlink retries on compound reads; no-delete root handles; observed direct-parent reads only with healthy monitoring and a queued FileId; retained ancestors for safe fallback; connection-scoped session, tree, file-ID, and bound native-path checks |\n| Linux local drive | Retained directory descriptors, `openat2` with no-link, no-mount, and beneath-root resolution; component-by-component fallback when the syscall is unavailable; exact names and mount checks; kernel pseudo-filesystems and device-tree aliases excluded |\n| Windows local drive | No-delete bound-root handles, delete-sharing full-pass parent handles, 128-bit file IDs, volume and native-device paths; bounded enumeration and strict UTF-16 decoding |\n\nThe SMB boundary is logical: the configured share and folder. A configured subfolder is not an access-control boundary; the connection credentials can access the share. Storage mounted inside a share can be indexed; SMB does not promise physical-volume containment. DFS shares and reported reparse descendants remain excluded. Local traversal does not cross mounts. Windows junctions, name-surrogate redirections, cloud placeholders, and unknown reparse tags are excluded rather than followed. Missing optional volume metadata does not weaken these traversal checks.\n\nSMB full passes check the bound root at the start and end. Between these checks, a known parent can use a direct no-follow open without an ancestor chain only while the recursive folder-change watcher is ready and the epoch has no observation-loss or read-capacity invalidation. The opened FileId must match the queue, the handle must not report a reparse point, and the requested native path, session, and tree must match the binding. Root and reconciliation reads, missing-parent recovery, and exact child checks retain the safe ancestor chain. Parents without a queued FileId also use the safe path.\n\nObservation protects index correctness on the direct path. An ancestor event rejects affected reads before publication. Tokens remain live until grouped commits and check watcher readiness again at commit. A late event corrects already committed rows through the normal mutation path; the index is eventually consistent with the watcher delay. If monitoring is lost during a pass, active observed reads are deferred and the pass continues with safe reads. Observation loss requeues completed parents for revalidation, while coverage can remain uncertain. Root and non-compound scan handles retain no-delete sharing.\n\nDuring a full pass, safe reads reuse the pinned share and configured-root handles. Between full probes, local checks require connected handles, a non-DFS tree, the same connection object and server GUID, and unchanged session and tree IDs. Descendant ancestor chains and target FileAll identity checks remain. Closing a parent read does not close the root handles. A source-read failure requests a full root probe before a later read; versioned requests preserve failures that occur during a probe. Standalone reconciliation retains full root checks rather than relying on full-pass boundaries.\n\nSafe reads reuse cached `FsVolume` metadata across handles on the same live tree. The cache matches the tree and connection objects plus the session and tree IDs. A changed binding requires a new volume query. Unsupported optional volume information is cached for that binding; permission and transport failures are not cached. This cache does not replace root or parent verification.\n\n### SMB Compound Reads\n\nThe observed reader sends one related compound: `CREATE`, `QUERY_INFO(FileInternalInformation)`, two `QUERY_DIRECTORY` requests, and `CLOSE`. The first directory query restarts enumeration; the second continues it. End-of-directory responses complete a small or empty directory in one round trip. If both queries return data, the reader discards those partial results and opens the parent again through the existing enumeration loop.\n\nEach query buffer is bounded by the negotiated transaction size, the shared 1 MiB maximum, and available credits. A connection without multi-credit support uses at most 64 KiB. Full scans send up to `scan_pipeline_depth` compounds before receiving the oldest result. The shared default is eight parents. All reads use one worker and the root's retained connection; reused session and tree IDs cannot admit a replacement transport.\n\nBefore each pipeline send, the reader checks the credit window under the connection lock and leaves `scan_credit_reserve` credits, with a shared default of 16. Scan requests ask for credit growth until the window can support the configured depth. If a compound cannot fit, the worker receives the oldest outstanding parent first. With no outstanding reads, it can send one bounded credit-growth echo per queue page, including when the window starts at one credit. If the server does not grant enough credits, the reader uses the existing loop instead.\n\nThe pool creates a `ScanCreditConnection` before transport setup and lets `smbclient` register its session with the configured authentication and encryption policy. Its reentrant sequence lock covers the full scan credit check and compound send. Ordinary browse sends use the same lock, so they cannot consume credits between the scan check and the library's per-message allocations. The check uses the library's negotiated credit charges, with a minimum of one credit per message. If the full compound and reserve do not fit, admission changes no sequence numbers or outstanding requests. The lock is released before receiving responses.\n\nConnections without this atomic-admission method use the existing loop instead of an unprotected pipeline send. A failed compound send still retires and aborts that connection generation rather than reusing uncertain request state.\n\nThe loop also adapts its query buffer before each request. It uses the negotiated transaction size and the shared 1 MiB maximum, then limits the size to the current credit budget. It leaves the browse reserve where possible, but retains a one-credit query when the window is small. Connections without multi-credit support use at most 64 KiB. These size estimates do not add atomic admission to loop reads; the whole-compound lock applies to pipeline sends.\n\nCompound handles allow read, write, and delete sharing because they open and close within the same request group. The reader disables client-side symlink retries and drains responses after a parent error. Each in-flight read has a deadline measured from submission. A timeout, including during cleanup after watcher loss, defers unfinished parents and retires the connection generation through the pool's abort path. A mutation barrier on one parent defers only that parent; unrelated valid results remain eligible for grouped commit in queue order. Watcher loss defers all outstanding observed reads before the pass continues with safe traversal.\n\nFileId mismatches, reparse attributes, malformed responses, and listings that make no progress cannot publish children. Missing-path and access-denied responses retain their existing cache error handling. Buffered results still check observation and local root binding during enumeration and before commit. Exact child checks reopen the safe retained-ancestor reader.\n\nThe drive browser and local index share one classifier. USB, SD, MMC, and hot-plug disks are removable even when Windows reports a fixed drive. Failed classification uses the unknown class. Fixed drives select another index only when available volume serial or UUID evidence changes. Removable and unknown drives also replace the current generation when available label, file-system type, or total-capacity evidence changes. Generation replacement selects the new generation and deletes the old one in one transaction. Unchanged volume evidence does not rewrite source metadata. Missing evidence and drive-class changes alone do not replace data. Windows uses the 64-bit serial from `FILE_ID_INFO`, including zero. Local file IDs are session-scoped checks, not replacement signals.\n\nVolume evidence is checked again when the root binds. An unmounted Linux source stays unavailable instead of indexing its mount-point folder. Linux mount checks use descriptor-bound `statx` mount IDs with `/proc/self/fdinfo` as a fallback. A missing mount-boundary capability stops that source until Companion restarts. Idle removable sources without active work or a watcher release their root handles. Windows removal notifications pause source work and release handles before removal is allowed.\n\nDepth and path-length bounds are defined in `shared/directory-index/contract.json`. Excluded descendants produce partial coverage while readable branches continue.\n\nLinux enumeration uses `d_type` to skip regular files without a metadata call. Unknown entry types use a no-follow metadata check. A no-follow `statx` checks each directory child's inode and mount without opening the child. Missing statx fields use the descriptor fallback. Windows enumeration uses a 1 MiB buffer and validates names, attributes, reparse tags, and full 128-bit FileIds from directory records without opening each child.\n\nA native scan uses one `NativeParent` read through enumeration, batch validation, issue handling, and parent completion. It checks the queued identity before processing children and keeps the observation token checks before writes. Linux retains the parent descriptor and gives `fdopendir` a duplicate, so enumeration cannot close the original. Descriptor checks reject a deleted parent without reopening its path. If the watcher is missing, failed, or not yet ready, Linux also checks the root-relative parent identity before each child batch and final parent completion, including parallel full-pass and reconciliation reads. A healthy watcher adds no parent opens at these boundaries. Windows full-pass reads use FileId opens, relative no-reparse opens, or the checked ancestor fallback. Non-root scan handles permit read, write, and delete sharing. The bound root and strict standalone reads keep no-delete sharing. Identity and native-path checks reject a moved parent before publication. Missing-parent recovery uses exact child lookups under the retained parent.\n\nFull passes read independent parents with at most four native worker threads, defined by `scan_read_parallelism`. A bounded channel sends child batches, issues, and completion to the scan thread; workers never write the index. Each read retains its handle and observation token until publication or discard. Queued ancestors finish and commit before their descendants start, so changed FileIds reach later reads. Cancellation and storage failure stop new jobs, drain ownership, and join all workers.\n\nBackend initialization withholds rows until a handle-bound root probe succeeds. Root failure returns HTTP 503 without deleting accepted data. Descendant access denial produces partial coverage instead. Late results cannot restore an invalidated source.\n\n### SQLite Storage\n\n| Runtime | Location and driver |\n|---|---|\n| Backend | `data/directory_cache/sqlite/`, or `sqlite/` below `directory_cache_location`; standard Python `sqlite3` with Debian system SQLite |\n| Companion | `directory-index/sqlite/` in the OS-user cache directory; bundled Rust SQLite binding |\n\nIndexes are disposable directory data, separate from recent history. Stored source metadata excludes passwords. `shared/directory-index/` owns the schema, search normalization, validation rules, and contract fixtures.\n\nSchema version 5 retains nullable FileIds in `scan_queue`: eight bytes for SMB and Linux, and 16 bytes for Windows. Root and observed-parent entries can omit an identity. Child identities commit with directory rows and survive a deferred read or reopen. Full passes and reconciliation refresh existing queue rows when a parent listing supplies a different non-null identity. Reconciliation does not insert a job for an existing child that has no queue row. A change from a known identity requeues completed child work; a change from an unknown identity keeps its processed state. Unchanged identities cause no queue writes. Readers compare a queued identity before publishing children. Companion can first commit a fresh buffered parent listing to update that identity. A confirmed mismatch is an unsafe item issue.\n\nDirectory rows have a nullable `parent_id` and the `directories_parent(generation_id, parent_id)` index. Stored links must identify an immediate parent in the same generation. Deletes cascade to linked descendants, their FTS entries, and their queue rows. Adds and moves maintain parent links. Both scanners diff complete and streamed parent snapshots and finish their queue rows in one transaction without rewriting unchanged directory or FTS rows. Early batches store their names in `scan_snapshot_children`. Final completion removes absent linked subtrees, clears staged names, and completes the parent atomically. Failed parents suppress deletions. Old-schema indexes rebuild through disposable-cache recovery; recent history is not changed.\n\nItem issue counts belong to the producer's observation token. Full passes buffer these counts until the completed parent snapshot commits; reconciliation commits them with the final parent snapshot. Early incomplete child batches retain the pending counts. A stale token discards them and leaves its parent pending. Counts aggregate by issue code in the parent transaction, so coverage, revision, directory changes, and parent completion roll back together if a write fails. Buffered issue payloads count toward the group byte bound.\n\nThe selected generation records `scan_pass_id` and `scan_active`. A fresh verification resets its queue completion flags and starts a new pass; an interrupted active pass resumes without that reset. A completed pass keeps the selected generation ID. The clean-shutdown marker is cleared on open and set only after a clean, transaction-free close with ready search tokens. A clean reopen skips SQLite `quick_check` and the FTS integrity command when the FTS schema is intact. An unclean reopen runs both checks. Schema, foreign-key, generation, and storage-binding validation still run on every open. Reopen retains valid streamed snapshot names; the first restarted batch replaces them. Invalid names or snapshots owned by completed parents trigger disposable-cache recovery.\n\nBoth stores use WAL and `synchronous=NORMAL`. The index is a verified cache, not the source of directory data. A power failure can lose recent cache commits; interrupted or uncommitted work remains pending for verification. Writes, checkpoints, maintenance, and close are serialized through the writer. Queries use read-only connections and explicit transactions. Both runtimes reuse isolated read connections and check their storage binding before each query. Query cancellation handlers are cleared before reuse. Storage leases remain held until admitted readers and workers finish; active database families cannot be evicted.\n\nScan writes use bounded parent groups. Content-changing groups have a 250 ms maximum wait and a 1,000-parent cap. Bookkeeping-only groups have a 1 s maximum wait and a 20,000-parent cap. Each interval starts with the first parent, not the previous commit. Both groups commit early at the parent cap or the shared byte bound; parent names count toward that bound. Independent work pages do not force a commit. Ancestor dependencies, error transitions, and pass completion can require an earlier commit. Each completed parent keeps its observation token and barriers until commit, but no longer uses active-reader capacity. The next page excludes completed buffered parents. A stale parent remains pending; valid parents in the group can commit. Large parent reads can publish child batches before the parent is complete.\n\nReconciliation uses the same adaptive groups as full passes without advancing the full-verification clock. Queue paths and FileIds are read in pages, and buffered completed parents are excluded from later pages. Ancestors commit before queued descendants start. Backend reconciliation uses the page's FileIds and keeps its per-parent worker deadline. Native reconciliation uses the bounded worker scheduler but retains strict root and parent opens, rather than full-pass fast opens. Early snapshots, issue counts, stale deferral, and ownership cleanup use the reconciliation generation checks. Status snapshots refresh after group commits.\n\nEmpty-query status uses committed metadata snapshots in memory. It does not open SQLite connections or run a directory query. The optional `scan_progress` response contains the phase, completed and queued parent counts, directory count, and start timestamp. Each group commit refreshes progress. The frontend shows active build or update progress before uncertain coverage.\n\nStorage must be private and local. Opens and cleanup validate directory ownership, file identity, and aliases. Do not write to managed databases externally or weaken these checks to permit a path-only fallback.\n\n### Resource Controls\n\nWorker counts, batches, and observation queues are bounded by the shared contract. Disk growth requires headroom and free-space admission. Native full-pass and reconciliation groups share one disk reservation for their writes. Ordinary admission reuses its free-space sample for the final reservation check while holding the accounting lock. If cleanup runs, admission takes a fresh sample before it reserves space. Outstanding reservations remain part of both budget and physical-space checks. Maintenance yields to active work.\n\nAutomatic full passes have a minimum spacing of 30 seconds, defined in the shared contract. Requests cannot bypass this limit or failure backoff. Interrupted passes retain completed directory work and item issues. After an observation gap, retained directory reads are revalidated in bounded batches before pass acceptance. Parent reconciliation does not start a new full pass or advance the full-verification clock.\n\nPolicy defaults and ranges belong to `shared/directory-index/contract.json`. A lower budget may pause growth but must not trim active data. Eviction applies only to inactive, unowned indexes. Disk and cache settings are not hard filesystem or process-memory ceilings.\n\nSee [Directory-Index Policy Delivery](../../companion-architecture/local-drive-and-save-back-pipeline/#directory-index-policy-delivery) for Companion ownership and [Manage Directory Search](../../../admin-guide/operations-and-maintenance/manage-directory-search/) for administration.\n\n### Recovery and Shutdown\n\nStartup validates source identity and application consistency before exposing rows. Damaged search tokens rebuild from validated directory rows. Replacement is restricted to recognized invalid index data; permission, capacity, busy-storage, and general I/O failures must not trigger discard.\n\nFailures use bounded retries. Requests must not bypass retry deadlines. Access updates only the last-access time; an idle gap does not invalidate observations or make a running source unavailable. Idle sources release resources only when no worker, reader, or queued scan work remains. Released sources revalidate the root on reuse. Shutdown waits for admitted work before closing storage and root ownership, even when a request has been cancelled.\n\nFor the backend, scan work waits for both the resource-failure and observation-retry gates. The scan delay is therefore the later active deadline. `retry_after_ms` reports the earlier of that scan deadline and the next watcher retry. Status requests and searches do not move these deadlines. A local stale read uses the one-second observation retry, not a new failure backoff or a new full-pass interval.\n\nBackend and Companion epoch invalidations record a diagnostic reason: `watcher_start`, `observation_loss`, `source_rebind`, `read_capacity`, `stalled_read`, or `lifecycle`. These cover first notification setup, lost observations, source rebinding, exhausted read admission, stalled workers, and lifecycle changes. All reasons request verification. All reasons except `stalled_read` also mark coverage uncertain, because they can lose source events. A stalled read loses no events, so the next accepted pass can verify the index. Epoch and ownership checks reject stale work. The SMB observed path also stays disabled in an epoch with observation loss or exhausted read capacity, even after the queue-revalidation flag is consumed. Each invalidation logs its reason and a counter at INFO, including repeated reasons. Pass start and finish events also use INFO. Finish events include parent and directory counts, group commits, duration, and an abort reason when the pass fails.\n\nIndex recovery does not reset a shared SMB connection or remove recent-directory history. A source binding mismatch pauses publication, re-binds source handles, and schedules verification. Source and storage failures are not evidence that a directory was deleted.\n\nSMB setup runs outside the shared pool lock. Concurrent requests share setup for the same private cache. The pool bounds admitted work, setup tasks, and retained connection generations, both per source and across the process. A retired generation keeps its own cache until its workers and cleanup finish; replacement requests use a separate cache. Capacity failures return retry information rather than enter an unbounded queue. Shutdown stops new admission. Writes are not replayed automatically.\n\nA caller timeout or cancellation does not itself stop a blocking SMB operation. Reader handles, connection leases, and worker permits remain owned until actual completion. Late successful opens are closed before their leases are released.\n\nAn operation deadline retires its connection generation and requests one pool-owned transport abort through public `Connection.disconnect(close=False)`. The abort runs outside the event loop and pool lock, uses a snapshot of that generation's connections, and does not send session logoff requests or touch replacement connections. Ordinary caller cancellation retains work without aborting unrelated operations on the shared generation. Long-lived watcher subscriptions use their own lifecycle, not ordinary operation deadlines.\n\nPublic abort wakes blocked receive requests in the installed client. It cannot provide a universal operation deadline: disconnect shares a lock with socket send and can remain blocked behind a send. Abort work retains capacity until it exits. If workers cannot finish, admission remains bounded and requests return capacity errors. Wait before retrying; restart the backend service if retained work continues to occupy capacity.\n\nA mutation interrupted by abort, or whose caller deadline expires after dispatch, has uncertain completion. The API reports `smb_mutation_uncertain` with `mutation_uncertain: true` and `recoverable: false`. Check the source before retrying; the change may already be applied. Sambee does not replay the write automatically.\n\nBackend and Companion watcher startup and native event failures trigger background recovery independently of index storage initialization. A successful scan does not clear an unavailable-watcher warning. Degraded verification remains active while monitoring is unavailable; recovered monitoring requires verification of the event gap.\n\nBackend status messages come from current conditions, in priority order: unavailable source, disk budget, storage initialization, stalled read, verification failure, update failure, observation loss, unavailable watcher, incomplete coverage, search-token rebuild, and continuous changes. Resolved conditions no longer leave old error text behind. A verification failure clears after a valid source-root check or after verification recovers. A successful read of an unrelated parent does not clear it. An update failure comes from the periodic loop and clears after a successful periodic iteration. A finished full pass clears observation loss, also when the pass has coverage issues; the coverage message then shows the remaining issue. Startup waiting, isolated local retries, and late first readiness do not themselves report source changes or observation loss. Actual watcher failures and observation gaps remain visible until their causes resolve.\n\nRecovery diagnostics use opaque source and lifecycle-generation IDs. Failure transitions record one sanitized cause; repeated failures use bounded summaries. Recovery logs omit private exception text and paths; third-party SMB payloads are not rendered. Scan summaries include duration even when a scan fails. Backend `directory_scan_finished` and `directory_retry_scheduled` events also include `invalidation_reason` and `stale_turns`, the count of consecutive stale turns with no completed parent.\n\nPass logs report source-owned I/O totals as per-pass differences: `smb_round_trips` for backend request groups and `native_opens` for companion directory-open attempts. See [Directory-Search Diagnostics](../../cross-cutting-systems/logging-and-localization/#directory-search-diagnostics) for the counter definitions and limits.\n\n### Quick-Bar Status Contract\n\nWork state, snapshot coverage, verification time, and monitoring health are separate. `monitoring_state` is `starting`, `healthy`, `recovering`, or `unavailable`. `retry_after_ms` is a relative delay from response receipt, not a timestamp. Missing or null fields mean that the server supplies no monitoring state or retry delay; they do not prove healthy monitoring.\n\n| Response or condition | Quick-bar behavior |\n|---|---|\n| Building or updating, without a retry delay | Show active work and check status again |\n| Paused work with a retry delay | Show the status message without an active-work spinner; wait before checking |\n| Empty data, uncertain coverage, or unavailable monitoring | Keep history available and continue bounded status checks |\n| Recoverable request failure | Keep accepted results for the same query, show failure, and retry |\n| Terminal or unsupported request failure | Stop automatic retries until reactivation or a source change |\n| Ready, healthy data without a warning | Stop periodic status checks |\n| Closed menu or hidden page | Stop periodic checks; reject stale responses when the query or source changes |\n\nStatus checks do not require a minimum search length. Empty-query activation initializes status and history. The directory provider limits retry delays to 1-60 seconds and uses a five-second fallback. Structured errors use `recoverable` and `retry_after_ms`; the client does not infer recovery rules from message text. Older responses without the shared search contract do not enable periodic status checks. Requests are bound to the current source, history client, storage capability revision, and request sequence. A replaced binding cannot publish old results, status, or retry timing.\n\n### Support Limits\n\nCompanion directory indexing supports Linux and Windows, not macOS. Drive visibility alone does not establish index support. Changes to native traversal or recovery require tests on the affected platform; cross-compilation does not validate runtime behavior.\n\n## Where to Continue\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): backend service ownership\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): uploads, moves, renames, and edit sessions\n- [Local-Drive and Save-Back Pipeline](../../companion-architecture/local-drive-and-save-back-pipeline/): companion file operations\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/#directory-search-diagnostics): directory-search diagnostics and privacy rules\n- [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/): test scope and repository gates\n\n## Validation Expectations\n\nSelect focused watcher, cache, storage, directory API, and SMB operation tests for the changed boundary. Verify source binding, partial failures, lost events, stale-read rejection, exact counts, and retained ownership through cancellation. For example:\n\n```bash\ncd backend\n.venv/bin/python -m pytest tests/test_directory_cache.py tests/test_directory_index_contract.py tests/test_directory_search.py tests/test_smb_backend.py\n.venv/bin/python -m mypy app\n```\n\nFor companion index changes, run the relevant Rust manager, storage, traversal, and handler tests. Add frontend checks when refresh, status, selection, or progressive result behavior changes.\n"}, "page_contents": {"0.7": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses two separate SMB2/SMB3 `CHANGE_NOTIFY` paths: one tells an open browser to refresh its directory listing; the other maintains the directory-search index. They have different subscription, event, and consistency rules.\n\n## Components\n\n| Component | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | Browser subscriptions, access checks, path-prefix mapping, and `directory_changed` delivery |\n| `backend/app/services/directory_monitor.py` | Shared per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | Per-connection index lifecycle, recursive directory-name notifications, and background verification |\n| `backend/app/services/directory_index.py` | SQLite storage, generations, search, and maintenance |\n| `backend/app/services/directory_traversal.py` | Handle-bound SMB enumeration, identity validation, and exact missing-child checks |\n| `companion/src-tauri/src/server/directory_manager.rs` | Local-drive index lifecycle, native observations, and background workers |\n| `backend/app/main.py` | Backend monitor and cache shutdown |\n\n## Browser Notifications\n\n### Subscriptions and Paths\n\n`DirectoryMonitor` shares one `MonitoredDirectory` per `connection_id:path`. The first subscriber starts it; the last unsubscribe stops it. A WebSocket disconnect must release that client's subscriptions.\n\nThe WebSocket layer uses user-facing paths. `ConnectionManager` applies the connection's `path_prefix` to obtain the native SMB path. Notification callbacks map that path back to the user-facing path before delivery. Subscription keys and native watch paths must not be used interchangeably.\n\n| Message | Example |\n|---|---|\n| Subscribe | `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n| Unsubscribe | `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n| Change notification | `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n\n### Events and Refreshes\n\nBrowser watchers observe file names, directory names, sizes, and last-write changes in the subscribed directory's immediate children. They do not watch the whole subtree. A deep write does not invalidate every ancestor listing, although metadata changes reported for an immediate child directory can trigger a refresh.\n\nThe browser retains loaded rows during automatic refresh, including an empty listing. It waits for an active listing request, combines notifications into one pending refresh, and starts at most one automatic refresh per second. Navigation and pane disposal cancel queued refreshes.\n\n`directory_changed` requests a new listing; it is not a file-difference protocol. See [File Browser and Navigation Model](../../frontend-architecture/file-browser-and-navigation-model/) for browser state and request handling.\n\n### Resource Ownership\n\nA monitor acquires its connection, session, tree, directory handle, and `FileSystemWatcher` in that order. Cleanup runs in reverse order, including after partial initialization.\n\nCancellation during startup retains the pending worker. When startup finishes, cleanup releases only the subscription acquired by that worker, not a replacement subscription. Shutdown rejects new monitor startup.\n\nTransient failures use capped exponential reconnect backoff with jitter. Recovery continues after fast retries are exhausted, while the subscription remains active. Deletion of the watched directory stops its monitor. A stopped monitor is not reused for new subscribers. Shutdown calls `shutdown_monitor()`; a worker that is still running retains its handles until it exits.\n\n## Directory-Index Consistency\n\nThe backend and companion maintain SQLite directory indexes through shared background managers, not per-request tree walks. Cold queries return status while initialization proceeds. Committed initial batches are searchable with partial coverage; result limits do not limit indexed coverage or exact match counts.\n\nThe index watcher observes directory-name changes recursively from the share root or configured prefix. Events drive parent reconciliation. Periodic full verification covers missed notifications; it must not become a full rescan on every navigation or query.\n\n### Generations and Observation Order\n\nFull verification updates the selected generation in place while retained data remains searchable. Interrupted first builds and active verification passes keep their rows, pass identity, and queued parents, including item issues and storage reopens. A completed full pass advances `last_verified_at_ms` even with item issues; incremental changes and queries do not. Each index retains one generation, with `building` for an initial build and `accepted` after completion.\n\nNon-root access failures, unsafe traversal, invalid names, and other item read errors do not stop a pass. The scanner skips an invalid name or completes a failed parent, then continues with readable siblings. A failed parent retains stored descendants, including batches already published during the current read. Acceptance retains the issue count and sets partial coverage. It clears the verification request and uses the regular verification interval, not a special item retry. Event loss still blocks acceptance and keeps coverage uncertain. Root, transport, authentication, resource-limit, and storage failures retain their retry and recovery rules.\n\nRead tokens and observation barriers reject stale results. Observed directory changes update the index and request verification, but they do not change coverage. Lost events or pending-observation queue overflow mark coverage uncertain and request verification without deleting retained data. Pass acceptance requires a valid root and no outstanding observations or reads that could invalidate the pass.\n\nDirectory rows, FTS entries, counts, issues, queued subtree work, and revision updates must remain transactionally consistent. Queries read results and metadata from one selected-generation transaction.\n\n### SMB Watcher Startup\n\nBackend initialization waits up to 10 seconds for the first watcher attempt before it probes the source root or scans directories. Success means that the first `CHANGE_NOTIFY` request has been sent and startup invalidation has completed, not just that the thread or connection has started. The wait is asynchronous and holds no scan slot, worker, coordinator lock, or generation lock.\n\nA connection failure, notification-start failure, or timeout permits fallback verification. Watcher retries continue in the background. A failed first attempt reports unavailable monitoring, not lost observations before monitoring started. The first-attempt result is separate from current monitoring readiness. Cancellation and shutdown remove the waiter and prevent a later scan from starting.\n\nIf the watcher first becomes ready during fallback verification, it changes the epoch. Pre-monitoring reads cannot commit. Verification resumes after the bounded observation retry; a valid root probe keeps retained results searchable. Normal successful startup captures its scan epoch after watcher setup and needs no startup retry.\n\n### SMB Barriers and Local Retries\n\nThe backend captures an epoch for each full pass without registering a pass-wide reader. A directory read depends on that directory, its direct children, and its ancestors. A barrier on a deeper descendant does not reject the ancestor listing. A root barrier rejects all content reads. Source-root availability probes check epoch and reader ownership, not directory-content barriers.\n\nObservations update the selected generation before their barriers retire. Barriers remain only while pending observations or older live parent reads need them. When retained barriers exceed their count or byte bound, they collapse to one current root barrier. Live content reads become stale, but the epoch does not change and pending hints remain available.\n\nA stale parent stays pending and moves to the queue tail in one transaction. Published child batches remain; deferral clears their staged snapshot names. The next read re-enumerates the parent and starts a fresh snapshot. Local stale reads, final-capture refusals, and transient parent errors do not invalidate unrelated completed work. Observation loss and exhausted read capacity cause bounded revalidation of retained completed parents. Other epoch changes do not restart completed parents.\n\nThe periodic loop checks due verification before incremental reconciliation. A full pass owns the selected generation's scan queue; separate reconciliation does not run during that pass. Completed buffered ancestors commit before descendants are selected, so deleted rows and refreshed FileIds take effect first. Stale reads use the one-second observation retry; source-wide failures keep the failure backoff. Quiet branches can progress, but a full pass cannot be guaranteed to finish while relevant directories keep changing.\n\nLarge reads store early snapshot names in `scan_snapshot_children`, owned by the pending parent queue row. This keeps memory bounded without separate per-child absence requests. The final diff considers both staged names and the final child batch. Direct-child changes still reject the read before parent completion. Failed parent reads preserve stored children instead of applying an incomplete deletion diff.\n\n### Parent Reconciliation\n\nBackground workers reconcile affected parents between full passes. Renames check both parents, and new directories trigger descendant reads. A completed listing under a held, validated parent drives the atomic child diff; an incomplete listing or access error cannot delete missing children. Streamed reads use the same disk-backed snapshot names as full passes. An item error records partial coverage, completes the parent, and retains its stored subtree. Source-wide failures and stale observations leave work pending. Reconciliation does not establish full verification or clear uncertain coverage.\n\nFile operations queue parent hints before dispatch and after actual worker completion, including failure. New mutation paths must preserve this rule. Cancellation must not release worker ownership early or change the original operation result when hint delivery fails.\n\n### Source Identity and Traversal\n\nCatalogue names are SHA-256 hashes of source boundary settings. SMB uses the connection ID, host, port, share, configured folder, and username. Passwords, display names, connection edit times, and runtime session IDs do not change the file name. Local sources use the configured root path and, for fixed, removable, and unknown drives, available volume serial or file-system UUID evidence. Network and virtual drives use the root path alone. Runtime session IDs remain diagnostic values.\n\nReused rows are unverified until a verification pass completes. An SMB reconnect binds new handles and invalidates unfinished reads. Queued child FileIds are expected read identities, not proof of storage continuity. SMB server GUIDs and volume metadata are diagnostic values. File IDs of zero or all ones are unavailable and are not queued as expected identities. Session and tree IDs are compared only within one connection.\n\n| Source | Traversal rules |\n|---|---|\n| SMB | No automatic DFS or symlink retries on compound reads; no-delete root handles; observed direct-parent reads only with healthy monitoring and a queued FileId; retained ancestors for safe fallback; connection-scoped session, tree, file-ID, and bound native-path checks |\n| Linux local drive | Retained directory descriptors, `openat2` with no-link, no-mount, and beneath-root resolution; component-by-component fallback when the syscall is unavailable; exact names and mount checks; kernel pseudo-filesystems and device-tree aliases excluded |\n| Windows local drive | No-delete bound-root handles, delete-sharing full-pass parent handles, 128-bit file IDs, volume and native-device paths; bounded enumeration and strict UTF-16 decoding |\n\nThe SMB boundary is logical: the configured share and folder. A configured subfolder is not an access-control boundary; the connection credentials can access the share. Storage mounted inside a share can be indexed; SMB does not promise physical-volume containment. DFS shares and reported reparse descendants remain excluded. Local traversal does not cross mounts. Windows junctions, name-surrogate redirections, cloud placeholders, and unknown reparse tags are excluded rather than followed. Missing optional volume metadata does not weaken these traversal checks.\n\nSMB full passes check the bound root at the start and end. Between these checks, a known parent can use a direct no-follow open without an ancestor chain only while the recursive folder-change watcher is ready and the epoch has no observation-loss or read-capacity invalidation. The opened FileId must match the queue, the handle must not report a reparse point, and the requested native path, session, and tree must match the binding. Root and reconciliation reads, missing-parent recovery, and exact child checks retain the safe ancestor chain. Parents without a queued FileId also use the safe path.\n\nObservation protects index correctness on the direct path. An ancestor event rejects affected reads before publication. Tokens remain live until grouped commits and check watcher readiness again at commit. A late event corrects already committed rows through the normal mutation path; the index is eventually consistent with the watcher delay. If monitoring is lost during a pass, active observed reads are deferred and the pass continues with safe reads. Observation loss requeues completed parents for revalidation, while coverage can remain uncertain. Root and non-compound scan handles retain no-delete sharing.\n\nDuring a full pass, safe reads reuse the pinned share and configured-root handles. Between full probes, local checks require connected handles, a non-DFS tree, the same connection object and server GUID, and unchanged session and tree IDs. Descendant ancestor chains and target FileAll identity checks remain. Closing a parent read does not close the root handles. A source-read failure requests a full root probe before a later read; versioned requests preserve failures that occur during a probe. Standalone reconciliation retains full root checks rather than relying on full-pass boundaries.\n\nSafe reads reuse cached `FsVolume` metadata across handles on the same live tree. The cache matches the tree and connection objects plus the session and tree IDs. A changed binding requires a new volume query. Unsupported optional volume information is cached for that binding; permission and transport failures are not cached. This cache does not replace root or parent verification.\n\n### SMB Compound Reads\n\nThe observed reader sends one related compound: `CREATE`, `QUERY_INFO(FileInternalInformation)`, two `QUERY_DIRECTORY` requests, and `CLOSE`. The first directory query restarts enumeration; the second continues it. End-of-directory responses complete a small or empty directory in one round trip. If both queries return data, the reader discards those partial results and opens the parent again through the existing enumeration loop.\n\nEach query buffer is bounded by the negotiated transaction size, the shared 1 MiB maximum, and available credits. A connection without multi-credit support uses at most 64 KiB. Full scans send up to `scan_pipeline_depth` compounds before receiving the oldest result. The shared default is eight parents. All reads use one worker and the root's retained connection; reused session and tree IDs cannot admit a replacement transport.\n\nBefore each pipeline send, the reader checks the credit window under the connection lock and leaves `scan_credit_reserve` credits, with a shared default of 16. Scan requests ask for credit growth until the window can support the configured depth. If a compound cannot fit, the worker receives the oldest outstanding parent first. With no outstanding reads, it can send one bounded credit-growth echo per queue page, including when the window starts at one credit. If the server does not grant enough credits, the reader uses the existing loop instead.\n\nThe pool creates a `ScanCreditConnection` before transport setup and lets `smbclient` register its session with the configured authentication and encryption policy. Its reentrant sequence lock covers the full scan credit check and compound send. Ordinary browse sends use the same lock, so they cannot consume credits between the scan check and the library's per-message allocations. The check uses the library's negotiated credit charges, with a minimum of one credit per message. If the full compound and reserve do not fit, admission changes no sequence numbers or outstanding requests. The lock is released before receiving responses.\n\nConnections without this atomic-admission method use the existing loop instead of an unprotected pipeline send. A failed compound send still retires and aborts that connection generation rather than reusing uncertain request state.\n\nThe loop also adapts its query buffer before each request. It uses the negotiated transaction size and the shared 1 MiB maximum, then limits the size to the current credit budget. It leaves the browse reserve where possible, but retains a one-credit query when the window is small. Connections without multi-credit support use at most 64 KiB. These size estimates do not add atomic admission to loop reads; the whole-compound lock applies to pipeline sends.\n\nCompound handles allow read, write, and delete sharing because they open and close within the same request group. The reader disables client-side symlink retries and drains responses after a parent error. Each in-flight read has a deadline measured from submission. A timeout, including during cleanup after watcher loss, defers unfinished parents and retires the connection generation through the pool's abort path. A mutation barrier on one parent defers only that parent; unrelated valid results remain eligible for grouped commit in queue order. Watcher loss defers all outstanding observed reads before the pass continues with safe traversal.\n\nFileId mismatches, reparse attributes, malformed responses, and listings that make no progress cannot publish children. Missing-path and access-denied responses retain their existing cache error handling. Buffered results still check observation and local root binding during enumeration and before commit. Exact child checks reopen the safe retained-ancestor reader.\n\nThe drive browser and local index share one classifier. USB, SD, MMC, and hot-plug disks are removable even when Windows reports a fixed drive. Failed classification uses the unknown class. Fixed drives select another index only when available volume serial or UUID evidence changes. Removable and unknown drives also replace the current generation when available label, file-system type, or total-capacity evidence changes. Generation replacement selects the new generation and deletes the old one in one transaction. Unchanged volume evidence does not rewrite source metadata. Missing evidence and drive-class changes alone do not replace data. Windows uses the 64-bit serial from `FILE_ID_INFO`, including zero. Local file IDs are session-scoped checks, not replacement signals.\n\nVolume evidence is checked again when the root binds. An unmounted Linux source stays unavailable instead of indexing its mount-point folder. Linux mount checks use descriptor-bound `statx` mount IDs with `/proc/self/fdinfo` as a fallback. A missing mount-boundary capability stops that source until Companion restarts. Idle removable sources without active work or a watcher release their root handles. Windows removal notifications pause source work and release handles before removal is allowed.\n\nDepth and path-length bounds are defined in `shared/directory-index/contract.json`. Excluded descendants produce partial coverage while readable branches continue.\n\nLinux enumeration uses `d_type` to skip regular files without a metadata call. Unknown entry types use a no-follow metadata check. A no-follow `statx` checks each directory child's inode and mount without opening the child. Missing statx fields use the descriptor fallback. Windows enumeration uses a 1 MiB buffer and validates names, attributes, reparse tags, and full 128-bit FileIds from directory records without opening each child.\n\nA native scan uses one `NativeParent` read through enumeration, batch validation, issue handling, and parent completion. It checks the queued identity before processing children and keeps the observation token checks before writes. Linux retains the parent descriptor and gives `fdopendir` a duplicate, so enumeration cannot close the original. Descriptor checks reject a deleted parent without reopening its path. If the watcher is missing, failed, or not yet ready, Linux also checks the root-relative parent identity before each child batch and final parent completion, including parallel full-pass and reconciliation reads. A healthy watcher adds no parent opens at these boundaries. Windows full-pass reads use FileId opens, relative no-reparse opens, or the checked ancestor fallback. Non-root scan handles permit read, write, and delete sharing. The bound root and strict standalone reads keep no-delete sharing. Identity and native-path checks reject a moved parent before publication. Missing-parent recovery uses exact child lookups under the retained parent.\n\nFull passes read independent parents with at most four native worker threads, defined by `scan_read_parallelism`. A bounded channel sends child batches, issues, and completion to the scan thread; workers never write the index. Each read retains its handle and observation token until publication or discard. Queued ancestors finish and commit before their descendants start, so changed FileIds reach later reads. Cancellation and storage failure stop new jobs, drain ownership, and join all workers.\n\nBackend initialization withholds rows until a handle-bound root probe succeeds. Root failure returns HTTP 503 without deleting accepted data. Descendant access denial produces partial coverage instead. Late results cannot restore an invalidated source.\n\n### SQLite Storage\n\n| Runtime | Location and driver |\n|---|---|\n| Backend | `data/directory_cache/sqlite/`, or `sqlite/` below `directory_cache_location`; standard Python `sqlite3` with Debian system SQLite |\n| Companion | `directory-index/sqlite/` in the OS-user cache directory; bundled Rust SQLite binding |\n\nIndexes are disposable directory data, separate from recent history. Stored source metadata excludes passwords. `shared/directory-index/` owns the schema, search normalization, validation rules, and contract fixtures.\n\nSchema version 5 retains nullable FileIds in `scan_queue`: eight bytes for SMB and Linux, and 16 bytes for Windows. Root and observed-parent entries can omit an identity. Child identities commit with directory rows and survive a deferred read or reopen. Full passes and reconciliation refresh existing queue rows when a parent listing supplies a different non-null identity. Reconciliation does not insert a job for an existing child that has no queue row. A change from a known identity requeues completed child work; a change from an unknown identity keeps its processed state. Unchanged identities cause no queue writes. Readers compare a queued identity before publishing children. Companion can first commit a fresh buffered parent listing to update that identity. A confirmed mismatch is an unsafe item issue.\n\nDirectory rows have a nullable `parent_id` and the `directories_parent(generation_id, parent_id)` index. Stored links must identify an immediate parent in the same generation. Deletes cascade to linked descendants, their FTS entries, and their queue rows. Adds and moves maintain parent links. Both scanners diff complete and streamed parent snapshots and finish their queue rows in one transaction without rewriting unchanged directory or FTS rows. Early batches store their names in `scan_snapshot_children`. Final completion removes absent linked subtrees, clears staged names, and completes the parent atomically. Failed parents suppress deletions. Old-schema indexes rebuild through disposable-cache recovery; recent history is not changed.\n\nItem issue counts belong to the producer's observation token. Full passes buffer these counts until the completed parent snapshot commits; reconciliation commits them with the final parent snapshot. Early incomplete child batches retain the pending counts. A stale token discards them and leaves its parent pending. Counts aggregate by issue code in the parent transaction, so coverage, revision, directory changes, and parent completion roll back together if a write fails. Buffered issue payloads count toward the group byte bound.\n\nThe selected generation records `scan_pass_id` and `scan_active`. A fresh verification resets its queue completion flags and starts a new pass; an interrupted active pass resumes without that reset. A completed pass keeps the selected generation ID. The clean-shutdown marker is cleared on open and set only after a clean, transaction-free close with ready search tokens. A clean reopen skips SQLite `quick_check` and the FTS integrity command when the FTS schema is intact. An unclean reopen runs both checks. Schema, foreign-key, generation, and storage-binding validation still run on every open. Reopen retains valid streamed snapshot names; the first restarted batch replaces them. Invalid names or snapshots owned by completed parents trigger disposable-cache recovery.\n\nBoth stores use WAL and `synchronous=NORMAL`. The index is a verified cache, not the source of directory data. A power failure can lose recent cache commits; interrupted or uncommitted work remains pending for verification. Writes, checkpoints, maintenance, and close are serialized through the writer. Queries use read-only connections and explicit transactions. Both runtimes reuse isolated read connections and check their storage binding before each query. Query cancellation handlers are cleared before reuse. Storage leases remain held until admitted readers and workers finish; active database families cannot be evicted.\n\nScan writes use bounded parent groups. Content-changing groups have a 250 ms maximum wait and a 1,000-parent cap. Bookkeeping-only groups have a 1 s maximum wait and a 20,000-parent cap. Each interval starts with the first parent, not the previous commit. Both groups commit early at the parent cap or the shared byte bound; parent names count toward that bound. Independent work pages do not force a commit. Ancestor dependencies, error transitions, and pass completion can require an earlier commit. Each completed parent keeps its observation token and barriers until commit, but no longer uses active-reader capacity. The next page excludes completed buffered parents. A stale parent remains pending; valid parents in the group can commit. Large parent reads can publish child batches before the parent is complete.\n\nReconciliation uses the same adaptive groups as full passes without advancing the full-verification clock. Queue paths and FileIds are read in pages, and buffered completed parents are excluded from later pages. Ancestors commit before queued descendants start. Backend reconciliation uses the page's FileIds and keeps its per-parent worker deadline. Native reconciliation uses the bounded worker scheduler but retains strict root and parent opens, rather than full-pass fast opens. Early snapshots, issue counts, stale deferral, and ownership cleanup use the reconciliation generation checks. Status snapshots refresh after group commits.\n\nEmpty-query status uses committed metadata snapshots in memory. It does not open SQLite connections or run a directory query. The optional `scan_progress` response contains the phase, completed and queued parent counts, directory count, and start timestamp. Each group commit refreshes progress. The frontend shows active build or update progress before uncertain coverage.\n\nStorage must be private and local. Opens and cleanup validate directory ownership, file identity, and aliases. Do not write to managed databases externally or weaken these checks to permit a path-only fallback.\n\n### Resource Controls\n\nWorker counts, batches, and observation queues are bounded by the shared contract. Disk growth requires headroom and free-space admission. Native full-pass and reconciliation groups share one disk reservation for their writes. Ordinary admission reuses its free-space sample for the final reservation check while holding the accounting lock. If cleanup runs, admission takes a fresh sample before it reserves space. Outstanding reservations remain part of both budget and physical-space checks. Maintenance yields to active work.\n\nAutomatic full passes have a minimum spacing of 30 seconds, defined in the shared contract. Requests cannot bypass this limit or failure backoff. Interrupted passes retain completed directory work and item issues. After an observation gap, retained directory reads are revalidated in bounded batches before pass acceptance. Parent reconciliation does not start a new full pass or advance the full-verification clock.\n\nPolicy defaults and ranges belong to `shared/directory-index/contract.json`. A lower budget may pause growth but must not trim active data. Eviction applies only to inactive, unowned indexes. Disk and cache settings are not hard filesystem or process-memory ceilings.\n\nSee [Directory-Index Policy Delivery](../../companion-architecture/local-drive-and-save-back-pipeline/#directory-index-policy-delivery) for Companion ownership and [Manage Directory Search](../../../admin-guide/operations-and-maintenance/manage-directory-search/) for administration.\n\n### Recovery and Shutdown\n\nStartup validates source identity and application consistency before exposing rows. Damaged search tokens rebuild from validated directory rows. Replacement is restricted to recognized invalid index data; permission, capacity, busy-storage, and general I/O failures must not trigger discard.\n\nFailures use bounded retries. Requests must not bypass retry deadlines. Access updates only the last-access time; an idle gap does not invalidate observations or make a running source unavailable. Idle sources release resources only when no worker, reader, or queued scan work remains. Released sources revalidate the root on reuse. Shutdown waits for admitted work before closing storage and root ownership, even when a request has been cancelled.\n\nFor the backend, scan work waits for both the resource-failure and observation-retry gates. The scan delay is therefore the later active deadline. `retry_after_ms` reports the earlier of that scan deadline and the next watcher retry. Status requests and searches do not move these deadlines. A local stale read uses the one-second observation retry, not a new failure backoff or a new full-pass interval.\n\nBackend and Companion epoch invalidations record a diagnostic reason: `watcher_start`, `observation_loss`, `source_rebind`, `read_capacity`, `stalled_read`, or `lifecycle`. These cover first notification setup, lost observations, source rebinding, exhausted read admission, stalled workers, and lifecycle changes. All reasons request verification. All reasons except `stalled_read` also mark coverage uncertain, because they can lose source events. A stalled read loses no events, so the next accepted pass can verify the index. Epoch and ownership checks reject stale work. The SMB observed path also stays disabled in an epoch with observation loss or exhausted read capacity, even after the queue-revalidation flag is consumed. Each invalidation logs its reason and a counter at INFO, including repeated reasons. Pass start and finish events also use INFO. Finish events include parent and directory counts, group commits, duration, and an abort reason when the pass fails.\n\nIndex recovery does not reset a shared SMB connection or remove recent-directory history. A source binding mismatch pauses publication, re-binds source handles, and schedules verification. Source and storage failures are not evidence that a directory was deleted.\n\nSMB setup runs outside the shared pool lock. Concurrent requests share setup for the same private cache. The pool bounds admitted work, setup tasks, and retained connection generations, both per source and across the process. A retired generation keeps its own cache until its workers and cleanup finish; replacement requests use a separate cache. Capacity failures return retry information rather than enter an unbounded queue. Shutdown stops new admission. Writes are not replayed automatically.\n\nA caller timeout or cancellation does not itself stop a blocking SMB operation. Reader handles, connection leases, and worker permits remain owned until actual completion. Late successful opens are closed before their leases are released.\n\nAn operation deadline retires its connection generation and requests one pool-owned transport abort through public `Connection.disconnect(close=False)`. The abort runs outside the event loop and pool lock, uses a snapshot of that generation's connections, and does not send session logoff requests or touch replacement connections. Ordinary caller cancellation retains work without aborting unrelated operations on the shared generation. Long-lived watcher subscriptions use their own lifecycle, not ordinary operation deadlines.\n\nPublic abort wakes blocked receive requests in the installed client. It cannot provide a universal operation deadline: disconnect shares a lock with socket send and can remain blocked behind a send. Abort work retains capacity until it exits. If workers cannot finish, admission remains bounded and requests return capacity errors. Wait before retrying; restart the backend service if retained work continues to occupy capacity.\n\nA mutation interrupted by abort, or whose caller deadline expires after dispatch, has uncertain completion. The API reports `smb_mutation_uncertain` with `mutation_uncertain: true` and `recoverable: false`. Check the source before retrying; the change may already be applied. Sambee does not replay the write automatically.\n\nBackend and Companion watcher startup and native event failures trigger background recovery independently of index storage initialization. A successful scan does not clear an unavailable-watcher warning. Degraded verification remains active while monitoring is unavailable; recovered monitoring requires verification of the event gap.\n\nBackend status messages come from current conditions, in priority order: unavailable source, disk budget, storage initialization, stalled read, verification failure, update failure, observation loss, unavailable watcher, incomplete coverage, search-token rebuild, and continuous changes. Resolved conditions no longer leave old error text behind. A verification failure clears after a valid source-root check or after verification recovers. A successful read of an unrelated parent does not clear it. An update failure comes from the periodic loop and clears after a successful periodic iteration. A finished full pass clears observation loss, also when the pass has coverage issues; the coverage message then shows the remaining issue. Startup waiting, isolated local retries, and late first readiness do not themselves report source changes or observation loss. Actual watcher failures and observation gaps remain visible until their causes resolve.\n\nRecovery diagnostics use opaque source and lifecycle-generation IDs. Failure transitions record one sanitized cause; repeated failures use bounded summaries. Recovery logs omit private exception text and paths; third-party SMB payloads are not rendered. Scan summaries include duration even when a scan fails. Backend `directory_scan_finished` and `directory_retry_scheduled` events also include `invalidation_reason` and `stale_turns`, the count of consecutive stale turns with no completed parent.\n\nPass logs report source-owned I/O totals as per-pass differences: `smb_round_trips` for backend request groups and `native_opens` for companion directory-open attempts. See [Directory-Search Diagnostics](../../cross-cutting-systems/logging-and-localization/#directory-search-diagnostics) for the counter definitions and limits.\n\n### Quick-Bar Status Contract\n\nWork state, snapshot coverage, verification time, and monitoring health are separate. `monitoring_state` is `starting`, `healthy`, `recovering`, or `unavailable`. `retry_after_ms` is a relative delay from response receipt, not a timestamp. Missing or null fields mean that the server supplies no monitoring state or retry delay; they do not prove healthy monitoring.\n\n| Response or condition | Quick-bar behavior |\n|---|---|\n| Building or updating, without a retry delay | Show active work and check status again |\n| Paused work with a retry delay | Show the status message without an active-work spinner; wait before checking |\n| Empty data, uncertain coverage, or unavailable monitoring | Keep history available and continue bounded status checks |\n| Recoverable request failure | Keep accepted results for the same query, show failure, and retry |\n| Terminal or unsupported request failure | Stop automatic retries until reactivation or a source change |\n| Ready, healthy data without a warning | Stop periodic status checks |\n| Closed menu or hidden page | Stop periodic checks; reject stale responses when the query or source changes |\n\nStatus checks do not require a minimum search length. Empty-query activation initializes status and history. The directory provider limits retry delays to 1-60 seconds and uses a five-second fallback. Structured errors use `recoverable` and `retry_after_ms`; the client does not infer recovery rules from message text. Older responses without the shared search contract do not enable periodic status checks. Requests are bound to the current source, history client, storage capability revision, and request sequence. A replaced binding cannot publish old results, status, or retry timing.\n\n### Support Limits\n\nCompanion directory indexing supports Linux and Windows, not macOS. Drive visibility alone does not establish index support. Changes to native traversal or recovery require tests on the affected platform; cross-compilation does not validate runtime behavior.\n\n## Where to Continue\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): backend service ownership\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): uploads, moves, renames, and edit sessions\n- [Local-Drive and Save-Back Pipeline](../../companion-architecture/local-drive-and-save-back-pipeline/): companion file operations\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/#directory-search-diagnostics): directory-search diagnostics and privacy rules\n- [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/): test scope and repository gates\n\n## Validation Expectations\n\nSelect focused watcher, cache, storage, directory API, and SMB operation tests for the changed boundary. Verify source binding, partial failures, lost events, stale-read rejection, exact counts, and retained ownership through cancellation. For example:\n\n```bash\ncd backend\n.venv/bin/python -m pytest tests/test_directory_cache.py tests/test_directory_index_contract.py tests/test_directory_search.py tests/test_smb_backend.py\n.venv/bin/python -m mypy app\n```\n\nFor companion index changes, run the relevant Rust manager, storage, traversal, and handler tests. Add frontend checks when refresh, status, selection, or progressive result behavior changes.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/file-operations-and-edit-locking", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "file-operations-and-edit-locking", "title": "File Operations And Edit Locking", "path": "developer-guide/backend-architecture/file-operations-and-edit-locking", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.8": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.9": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "1.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "2.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.8": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.9": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "1.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "2.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/frontend-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "frontend-architecture", "title": "Frontend Architecture", "path": "developer-guide/frontend-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "0.8": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "0.9": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "1.0": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "2.0": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/frontend-overview", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "frontend-overview", "title": "Frontend Overview", "path": "developer-guide/frontend-architecture/frontend-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.8": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.9": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "1.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "2.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.8": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.9": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "1.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "2.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/theming-system-and-theme-selection", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "theming-system-and-theme-selection", "title": "Theming System And Theme Selection", "path": "developer-guide/frontend-architecture/theming-system-and-theme-selection", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 5}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 53, "diff_removed": 263}}, "content_versions": {"0.7": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.8": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.9": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "1.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "2.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee has two built-in themes (`sambee-light` and `sambee-dark`), user-owned themes, and administrator-managed site themes. Built-in IDs stay stable across upgrades, so updating their palettes doesn't change anyone's selection.\n\n## Theme Data\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | Palette types and editor field labels |\n| `frontend/src/theme/themes.ts` | Built-in definitions with stable IDs |\n| `frontend/src/theme/themeDefinition.ts` | Editable color catalog, hex checks, and versioned import/export |\n| `frontend/src/theme/resolveSyntaxTheme.ts` | Non-mutating legacy syntax defaults and strict supplied-palette validation |\n| `frontend/src/theme/syntaxStyles.ts` | Shared token classes and locally inherited syntax variables |\n| `frontend/src/theme/palette.ts` | Shared effective palette for the app |\n| `frontend/src/theme/viewerStyles.ts` | Viewer and Markdown document surfaces |\n| `frontend/src/theme/ThemeContext.tsx` | Registry refresh and Material UI theme |\n| `frontend/src/pages/PreferencesSettings.tsx` | Selection grid and selected-theme actions |\n| `frontend/src/components/Settings/ThemeEditorDialog.tsx` | Responsive theme editor |\n| `backend/app/api/themes.py` | Validated theme operations and site default |\n\nEach editable theme has its own server row with a globally unique ID, scope, owner (for user themes), and version. Full built-in palettes remain in frontend code. The built-in `id`, `mode`, and `primary.main` fields live in `shared/companion-themes.json` and are reused by the backend and frontend. A new theme ID is assigned by the server; an ID in an imported file does not claim or replace a stored theme.\n\nColors use `#RRGGBB` or `#RRGGBBAA`; the server normalizes valid hex to uppercase. The role catalog includes primary, backgrounds, text, selection, links, viewer surfaces, Markdown document surfaces, syntax, search highlights, and alerts. File-type icons aren't theme roles. Derived colors such as scrollbar shades, focus rings, and `background.paper` compatibility aren't editor fields. Keyboard focus rings follow the theme's primary text color: 57% opacity in light mode and 94% in dark mode. Changing that text color changes the focus color too, including in copied themes; legacy saved focus colors are ignored. Choose primary text that remains readable against the theme's surfaces.\n\nEvery existing editable role remains required. The additive `components.syntax` group has eight roles: `keyword`, `string`, `number`, `comment`, `type`, `function`, `operator`, and `punctuation`. If the entire group is absent from a stored definition or version-1 import, the frontend resolves the matching built-in light/dark palette without mutating or saving the original. A supplied group must contain exactly all eight valid colors; partial groups, nulls, unknown keys, and invalid colors are rejected by both frontend and backend. Save, copy, and export include the resolved group through the existing API and version-1 envelope. No database migration or separate syntax preferences are needed. Older application releases may reject these newer exports.\n\n## Selection And Defaults\n\n`SambeeThemeProvider` combines built-ins with the current user's themes and shared site themes from `GET /api/themes`. The per-user selection is saved separately through `appearance.theme_id` in `PUT /api/auth/me/settings`. The backend reports whether that value is an explicit override.\n\nA user without an override follows the site default (initially `sambee-light`). A user who explicitly chooses `sambee-light` keeps that ID even if an administrator changes the site default. The selected ID points at a theme definition, never at a frozen copy of a built-in. The provider refreshes shared themes, the default, and user settings on initial load, tab focus, visibility return, and local writes. It discards out-of-date responses when the account changes.\n\nAppearance settings display Your themes, Site themes, then Built-in themes. Clicking a tile or selecting its radio applies the theme and creates an explicit user override, even when it already matches the site default. Moving focus between radios doesn't change the applied theme or the target of Copy, Edit, Delete, and Set as default. The Default chip is distinct from the selected radio. Copy keeps writable themes in their group and copies read-only themes into Your themes without applying the copy. Editing read-only themes permits inspection and Save copy, but not Save. Only an administrator can save or delete site themes or make a built-in or site theme the default.\n\n## Companion Theme Delivery\n\nCompanion follows the active user's resolved theme on the authoritative paired server through [Shared Settings Delivery](../../companion-architecture/browser-to-companion-trust-model/#shared-settings-delivery). The backend resolves built-in and stored themes and the site default. It hashes the small Companion payload independently of directory policy. Persisted theme changes trigger synchronization; unchanged digests are no-ops. Native `ThemeState` broadcasts to existing windows and supplies the current theme to new windows. Routine paired delivery must not use a theme in a deep-link URI; that path is only a bootstrap fallback and cannot replace managed settings.\n\n## Editing And Persistence\n\nThe editor uses a responsive dialog with collapsible color groups. A swatch opens an alpha-aware picker and each color has an editable hex field. Invalid text stays in the field without changing the valid draft. Changes in the editor aren't applied to the app until Save succeeds; Cancel discards the draft. Import replaces only the draft after validating a versioned JSON definition, and Export writes the same format.\n\n`POST /api/themes` creates a theme. Save copy opens a destination menu with Your themes for everyone and Site themes for administrators. It always creates a new theme in the chosen group without changing the applied selection. If its name already exists in that group, the editor adds ` (copy)` or a numbered copy suffix. Save updates only the opened theme in its existing group and cannot create a copy. `PUT /api/themes/{id}` and `DELETE /api/themes/{id}?version=...` require the version read by the client; a stale version returns HTTP 409. The server checks ownership, admin permissions, names, IDs, and palette completeness before committing. Bulk writes to `appearance.custom_themes` are no longer supported. Legacy syntax compatibility is limited to an entirely absent syntax group; it doesn't repair incomplete older definitions.\n\nDeleting a theme clears explicit selections referencing it. If it was the site default, that setting is cleared too; users without an override then fall back to Sambee light. An explicit selection of another theme is unaffected.\n\n## Component Guidance\n\nPrefer the effective colors in `resolveThemePalette` and the MUI palette to hard-coded surfaces. `background.default` is the normal application surface; `background.paper` resolves to the same value for MUI compatibility. Dark chrome and dialogs use the editable `background.chrome` role. Markdown code, tables, blockquotes, and heading borders use the built-in theme's explicit document colors.\n\nViewer toolbar foreground variants, scrollbars, and subdued states can still derive opacity-adjusted values from their source color. Keep fixed colors for assets and file-type icons separate from the editor palette.\n\n## Shared Syntax Highlighting\n\nText viewing/editing, Markdown source and rendered Markdown fences share the CodeMirror language registry and tag mapping in `codeMirrorHighlightingCore.ts`. `syntaxHighlighting.ts` defines application-owned language IDs, UTF-16 token ranges, categories and explicit results that indicate plain text. Native editors and the syntax worker reuse that implementation. Fence aliases resolve to existing lazy grammars, including `mssql` to MS SQL and `mariadb` to MariaDB SQL. A `.sql` filename continues to select standard SQL; unknown fence labels aren't guessed.\n\nThe live Markdown viewer collects exact code occurrences from ReactMarkdown's existing AST, without another collection parse or embedded editors. A dedicated cancellable worker prepares syntax sequentially with acknowledged source chunks of at most 16,384 UTF-16 units and result pages of at most 512 ranges. Blocks above 100,000 UTF-16 units stay plain text. Nested Markdown fences use the configured Markdown parser, up to four Markdown levels including the outer block. Unknown, unlabelled and explicit plain-text fences remain neutral. A nested grammar load failure, or a parser error during static fence startup or advancement, leaves only the failed fence plain while retaining enclosing Markdown structure and successful siblings. The static adapter doesn't mutate cached grammars or retry parsing; later fences and preparations can still succeed. Closing during a pending grammar load terminates the generation's worker; reopening starts a fresh preparation. Cancellation still propagates, and exceeding the nesting limit intentionally keeps the whole outer block plain without suppressing unrelated blocks. There's no aggregate document-length or block-count cutoff. The pre-app browser capability gate requires the Web Worker API; Worker-less app operation isn't supported. The helper's defensive main-thread fallback isn't a supported browser mode or a responsiveness guarantee.\n\nEach preview generation owns cancellation and stale-result guards. After all requested blocks finish, the viewer paints at most 4,000 viewport syntax ranges through CSS Highlights. Vertical and horizontal clipping avoid publishing off-screen token ranges; scrolling, viewport resize, image loads and font readiness refresh presentation. Publication doesn't replace text nodes or insert token spans, preserving native text, whitespace, selection and the cached preview-search index. Missing highlight/visibility capabilities leave syntax plain instead of falling back to token DOM mutation. Disposal removes owned highlights, style, observers, listeners and queued frames. First visible syntax, complete preparation, memory and native interaction acceptance remain separate rollout gates; see [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/).\n\nThe existing theme provider installs stable application token rules once. Viewer/editor surfaces publish locally inherited CSS variables from the resolved MUI syntax palette, so changing theme colors doesn't require reparsing code or replacing token DOM. Identifiers and neutral code inherit the existing code foreground. Markdown source headings and structural markers use `keyword`; links use the existing link role; inline code uses the existing code foreground. Emphasis, strong text, and strikethrough change only their corresponding semantic treatment, not source font sizes or line geometry. Embedded code uses code categories, not Markdown prose styling.\n\nThe shared mapping also preserves built-ins, properties and keys, booleans, null, regular expressions, escapes, and metadata/directives when the grammar supplies those tags. `TOKEN_COLOR_ROLES` maps these categories to the existing eight syntax colors: built-ins use `function`; properties and regular expressions use `type`; booleans, null, and metadata use `keyword`; escapes use `operator`. Editors and rendered fences share this mapping without another parse or a theme schema change. Built-in names aren't necessarily commands, and grammar classifications vary: PowerShell variables and bare words can both remain neutral identifiers. There are no language-specific classification overrides.\n\nSearch matches use the viewer text foreground instead of syntax colors so matched keywords remain readable against their highlight backgrounds. Source editors apply that foreground to the match and its nested tokens. Preview search inherits `--sambee-search-foreground` from its own viewer; syntax highlights have priority -1, ordinary search highlights 0, and the current match 1. The shared search-color helper preserves the configured hues and uses 30%/36% opacity for ordinary/current matches in light mode and 40%/44% in dark mode. Custom theme validation checks color format and completeness, not contrast; choose text, syntax and surface colors that remain readable after alpha blending.\n\nTheme updates and lazy grammar completion preserve native selection, the active search match and both scroll axes on all four surfaces. Theme changes don't restart syntax preparation or renormalize unchanged Markdown. Late grammar completion can update editor token spans, while preview publication retains its original text nodes. These state guarantees don't establish scrolling performance, native clipboard behavior or close/navigation acceptance.\n\nReplacing an editor doesn't require replacing static highlighting. Replacing the engine requires preserving the application's requirements for token ranges and highlighting results, aliases where supported, and viewer lifecycle. Classification parity with a different engine isn't automatic. Removing CodeMirror entirely also requires migrating native editor integrations such as commands, autocomplete, and tables.\n\n## Verification\n\nRun focused theme tests and the project checks after changing the palette, API, or editor:\n\n```bash\ncd frontend \u0026\u0026 npm run test -- src/theme/__tests__ src/pages/__tests__/PreferencesSettings.test.tsx\ncd frontend \u0026\u0026 npm run build \u0026\u0026 npm run lint\ncd backend \u0026\u0026 .venv/bin/python -m pytest tests/test_user_settings.py\n```\n\nCheck the Appearance grid and editor on a phone and desktop in both built-in modes. Verify selection and saved-theme refresh after focus, color picker keyboard use and placement, alpha values and export, Cancel without applying the draft, and stale-save feedback.\n\nFor the production theme-dialog browser regressions, build the frontend first and keep the existing frontend/backend dev servers running. From `frontend/`, run:\n\n```bash\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production syntax theme dialog' --workers=1\n```\n\nThe suite serves built assets and intercepts theme APIs at `http://localhost:3000/browse/smb/demo`; it doesn't change stored themes. Chromium and Firefox cover save/cancel/copy, validation focus, personal/site/built-in permissions, alpha values, unchanged selection after copying, and rejected-save feedback at 1543x900 and 390x600. Narrow desktop viewports don't replace testing on a physical phone or with assistive technology.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.8": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.9": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "1.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "2.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee has two built-in themes (`sambee-light` and `sambee-dark`), user-owned themes, and administrator-managed site themes. Built-in IDs stay stable across upgrades, so updating their palettes doesn't change anyone's selection.\n\n## Theme Data\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | Palette types and editor field labels |\n| `frontend/src/theme/themes.ts` | Built-in definitions with stable IDs |\n| `frontend/src/theme/themeDefinition.ts` | Editable color catalog, hex checks, and versioned import/export |\n| `frontend/src/theme/resolveSyntaxTheme.ts` | Non-mutating legacy syntax defaults and strict supplied-palette validation |\n| `frontend/src/theme/syntaxStyles.ts` | Shared token classes and locally inherited syntax variables |\n| `frontend/src/theme/palette.ts` | Shared effective palette for the app |\n| `frontend/src/theme/viewerStyles.ts` | Viewer and Markdown document surfaces |\n| `frontend/src/theme/ThemeContext.tsx` | Registry refresh and Material UI theme |\n| `frontend/src/pages/PreferencesSettings.tsx` | Selection grid and selected-theme actions |\n| `frontend/src/components/Settings/ThemeEditorDialog.tsx` | Responsive theme editor |\n| `backend/app/api/themes.py` | Validated theme operations and site default |\n\nEach editable theme has its own server row with a globally unique ID, scope, owner (for user themes), and version. Full built-in palettes remain in frontend code. The built-in `id`, `mode`, and `primary.main` fields live in `shared/companion-themes.json` and are reused by the backend and frontend. A new theme ID is assigned by the server; an ID in an imported file does not claim or replace a stored theme.\n\nColors use `#RRGGBB` or `#RRGGBBAA`; the server normalizes valid hex to uppercase. The role catalog includes primary, backgrounds, text, selection, links, viewer surfaces, Markdown document surfaces, syntax, search highlights, and alerts. File-type icons aren't theme roles. Derived colors such as scrollbar shades, focus rings, and `background.paper` compatibility aren't editor fields. Keyboard focus rings follow the theme's primary text color: 57% opacity in light mode and 94% in dark mode. Changing that text color changes the focus color too, including in copied themes; legacy saved focus colors are ignored. Choose primary text that remains readable against the theme's surfaces.\n\nEvery existing editable role remains required. The additive `components.syntax` group has eight roles: `keyword`, `string`, `number`, `comment`, `type`, `function`, `operator`, and `punctuation`. If the entire group is absent from a stored definition or version-1 import, the frontend resolves the matching built-in light/dark palette without mutating or saving the original. A supplied group must contain exactly all eight valid colors; partial groups, nulls, unknown keys, and invalid colors are rejected by both frontend and backend. Save, copy, and export include the resolved group through the existing API and version-1 envelope. No database migration or separate syntax preferences are needed. Older application releases may reject these newer exports.\n\n## Selection And Defaults\n\n`SambeeThemeProvider` combines built-ins with the current user's themes and shared site themes from `GET /api/themes`. The per-user selection is saved separately through `appearance.theme_id` in `PUT /api/auth/me/settings`. The backend reports whether that value is an explicit override.\n\nA user without an override follows the site default (initially `sambee-light`). A user who explicitly chooses `sambee-light` keeps that ID even if an administrator changes the site default. The selected ID points at a theme definition, never at a frozen copy of a built-in. The provider refreshes shared themes, the default, and user settings on initial load, tab focus, visibility return, and local writes. It discards out-of-date responses when the account changes.\n\nAppearance settings display Your themes, Site themes, then Built-in themes. Clicking a tile or selecting its radio applies the theme and creates an explicit user override, even when it already matches the site default. Moving focus between radios doesn't change the applied theme or the target of Copy, Edit, Delete, and Set as default. The Default chip is distinct from the selected radio. Copy keeps writable themes in their group and copies read-only themes into Your themes without applying the copy. Editing read-only themes permits inspection and Save copy, but not Save. Only an administrator can save or delete site themes or make a built-in or site theme the default.\n\n## Companion Theme Delivery\n\nCompanion follows the active user's resolved theme on the authoritative paired server through [Shared Settings Delivery](../../companion-architecture/browser-to-companion-trust-model/#shared-settings-delivery). The backend resolves built-in and stored themes and the site default. It hashes the small Companion payload independently of directory policy. Persisted theme changes trigger synchronization; unchanged digests are no-ops. Native `ThemeState` broadcasts to existing windows and supplies the current theme to new windows. Routine paired delivery must not use a theme in a deep-link URI; that path is only a bootstrap fallback and cannot replace managed settings.\n\n## Editing And Persistence\n\nThe editor uses a responsive dialog with collapsible color groups. A swatch opens an alpha-aware picker and each color has an editable hex field. Invalid text stays in the field without changing the valid draft. Changes in the editor aren't applied to the app until Save succeeds; Cancel discards the draft. Import replaces only the draft after validating a versioned JSON definition, and Export writes the same format.\n\n`POST /api/themes` creates a theme. Save copy opens a destination menu with Your themes for everyone and Site themes for administrators. It always creates a new theme in the chosen group without changing the applied selection. If its name already exists in that group, the editor adds ` (copy)` or a numbered copy suffix. Save updates only the opened theme in its existing group and cannot create a copy. `PUT /api/themes/{id}` and `DELETE /api/themes/{id}?version=...` require the version read by the client; a stale version returns HTTP 409. The server checks ownership, admin permissions, names, IDs, and palette completeness before committing. Bulk writes to `appearance.custom_themes` are no longer supported. Legacy syntax compatibility is limited to an entirely absent syntax group; it doesn't repair incomplete older definitions.\n\nDeleting a theme clears explicit selections referencing it. If it was the site default, that setting is cleared too; users without an override then fall back to Sambee light. An explicit selection of another theme is unaffected.\n\n## Component Guidance\n\nPrefer the effective colors in `resolveThemePalette` and the MUI palette to hard-coded surfaces. `background.default` is the normal application surface; `background.paper` resolves to the same value for MUI compatibility. Dark chrome and dialogs use the editable `background.chrome` role. Markdown code, tables, blockquotes, and heading borders use the built-in theme's explicit document colors.\n\nViewer toolbar foreground variants, scrollbars, and subdued states can still derive opacity-adjusted values from their source color. Keep fixed colors for assets and file-type icons separate from the editor palette.\n\n## Shared Syntax Highlighting\n\nText viewing/editing, Markdown source and rendered Markdown fences share the CodeMirror language registry and tag mapping in `codeMirrorHighlightingCore.ts`. `syntaxHighlighting.ts` defines application-owned language IDs, UTF-16 token ranges, categories and explicit results that indicate plain text. Native editors and the syntax worker reuse that implementation. Fence aliases resolve to existing lazy grammars, including `mssql` to MS SQL and `mariadb` to MariaDB SQL. A `.sql` filename continues to select standard SQL; unknown fence labels aren't guessed.\n\nThe live Markdown viewer collects exact code occurrences from ReactMarkdown's existing AST, without another collection parse or embedded editors. A dedicated cancellable worker prepares syntax sequentially with acknowledged source chunks of at most 16,384 UTF-16 units and result pages of at most 512 ranges. Blocks above 100,000 UTF-16 units stay plain text. Nested Markdown fences use the configured Markdown parser, up to four Markdown levels including the outer block. Unknown, unlabelled and explicit plain-text fences remain neutral. A nested grammar load failure, or a parser error during static fence startup or advancement, leaves only the failed fence plain while retaining enclosing Markdown structure and successful siblings. The static adapter doesn't mutate cached grammars or retry parsing; later fences and preparations can still succeed. Closing during a pending grammar load terminates the generation's worker; reopening starts a fresh preparation. Cancellation still propagates, and exceeding the nesting limit intentionally keeps the whole outer block plain without suppressing unrelated blocks. There's no aggregate document-length or block-count cutoff. The pre-app browser capability gate requires the Web Worker API; Worker-less app operation isn't supported. The helper's defensive main-thread fallback isn't a supported browser mode or a responsiveness guarantee.\n\nEach preview generation owns cancellation and stale-result guards. After all requested blocks finish, the viewer paints at most 4,000 viewport syntax ranges through CSS Highlights. Vertical and horizontal clipping avoid publishing off-screen token ranges; scrolling, viewport resize, image loads and font readiness refresh presentation. Publication doesn't replace text nodes or insert token spans, preserving native text, whitespace, selection and the cached preview-search index. Missing highlight/visibility capabilities leave syntax plain instead of falling back to token DOM mutation. Disposal removes owned highlights, style, observers, listeners and queued frames. First visible syntax, complete preparation, memory and native interaction acceptance remain separate rollout gates; see [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/).\n\nThe existing theme provider installs stable application token rules once. Viewer/editor surfaces publish locally inherited CSS variables from the resolved MUI syntax palette, so changing theme colors doesn't require reparsing code or replacing token DOM. Identifiers and neutral code inherit the existing code foreground. Markdown source headings and structural markers use `keyword`; links use the existing link role; inline code uses the existing code foreground. Emphasis, strong text, and strikethrough change only their corresponding semantic treatment, not source font sizes or line geometry. Embedded code uses code categories, not Markdown prose styling.\n\nThe shared mapping also preserves built-ins, properties and keys, booleans, null, regular expressions, escapes, and metadata/directives when the grammar supplies those tags. `TOKEN_COLOR_ROLES` maps these categories to the existing eight syntax colors: built-ins use `function`; properties and regular expressions use `type`; booleans, null, and metadata use `keyword`; escapes use `operator`. Editors and rendered fences share this mapping without another parse or a theme schema change. Built-in names aren't necessarily commands, and grammar classifications vary: PowerShell variables and bare words can both remain neutral identifiers. There are no language-specific classification overrides.\n\nSearch matches use the viewer text foreground instead of syntax colors so matched keywords remain readable against their highlight backgrounds. Source editors apply that foreground to the match and its nested tokens. Preview search inherits `--sambee-search-foreground` from its own viewer; syntax highlights have priority -1, ordinary search highlights 0, and the current match 1. The shared search-color helper preserves the configured hues and uses 30%/36% opacity for ordinary/current matches in light mode and 40%/44% in dark mode. Custom theme validation checks color format and completeness, not contrast; choose text, syntax and surface colors that remain readable after alpha blending.\n\nTheme updates and lazy grammar completion preserve native selection, the active search match and both scroll axes on all four surfaces. Theme changes don't restart syntax preparation or renormalize unchanged Markdown. Late grammar completion can update editor token spans, while preview publication retains its original text nodes. These state guarantees don't establish scrolling performance, native clipboard behavior or close/navigation acceptance.\n\nReplacing an editor doesn't require replacing static highlighting. Replacing the engine requires preserving the application's requirements for token ranges and highlighting results, aliases where supported, and viewer lifecycle. Classification parity with a different engine isn't automatic. Removing CodeMirror entirely also requires migrating native editor integrations such as commands, autocomplete, and tables.\n\n## Verification\n\nRun focused theme tests and the project checks after changing the palette, API, or editor:\n\n```bash\ncd frontend \u0026\u0026 npm run test -- src/theme/__tests__ src/pages/__tests__/PreferencesSettings.test.tsx\ncd frontend \u0026\u0026 npm run build \u0026\u0026 npm run lint\ncd backend \u0026\u0026 .venv/bin/python -m pytest tests/test_user_settings.py\n```\n\nCheck the Appearance grid and editor on a phone and desktop in both built-in modes. Verify selection and saved-theme refresh after focus, color picker keyboard use and placement, alpha values and export, Cancel without applying the draft, and stale-save feedback.\n\nFor the production theme-dialog browser regressions, build the frontend first and keep the existing frontend/backend dev servers running. From `frontend/`, run:\n\n```bash\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production syntax theme dialog' --workers=1\n```\n\nThe suite serves built assets and intercepts theme APIs at `http://localhost:3000/browse/smb/demo`; it doesn't change stored themes. Chromium and Firefox cover save/cancel/copy, validation focus, personal/site/built-in permissions, alpha values, unchanged selection after copying, and rejected-save feedback at 1543x900 and 390x600. Narrow desktop viewports don't replace testing on a physical phone or with assistive technology.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/file-browser-and-navigation-model", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "file-browser-and-navigation-model", "title": "File Browser And Navigation Model", "path": "developer-guide/frontend-architecture/file-browser-and-navigation-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 131, "diff_removed": 20}}, "content_versions": {"0.7": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.8": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.9": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "1.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "2.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/routing.ts` | parses and serializes typed directory, viewer, editor, and settings locations |\n| `pages/FileBrowser/useWorkspaceNavigation.ts` | resolves viewer targets and owns workspace navigation and safe overlay return entries |\n| `hooks/useRoutedViewerEditing.tsx` | connects the active editor's existing confirmation dialog to React Router navigation blocking |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## Real-Time Directory Refresh\n\n### Directory Navigation Failures\n\nPhysical directory navigation has a pending target and a displayed location. Load the target through the content provider before committing its connection, path, rows, and route. A failed navigation keeps the previous displayed location, selection, and scroll state. Request cancellation and location guards reject late responses, including responses from automatic parent recovery.\n\nOnly successfully loaded physical directories become file-list subscription targets. Missing initial locations and deleted current directories recover to an accessible parent, or clear stale rows and keep recovery controls visible. Canonical recovery replaces the affected route; it does not use browser Back or change the other pane.\n\nThe SMB storage boundary translates named missing-name, missing-parent, access-denied, and wrong-type statuses into typed storage errors. Directory listing returns a structured API code and a safe message. Only a confirmed `directory_not_found` result permits stale history and directory-index removal. A connection-level HTTP 404 is not proof that a folder was deleted.\n\nCompanion directory listings use the same `directory_not_found`, `directory_access_denied`, `not_a_directory`, and `directory_unavailable` codes. Companion responses put `code` beside the safe `detail` string; SMB responses put the code inside `detail`. The pane accepts both formats. Local path validation and directory reads use the directory error mapper, while unavailable drive roots remain separate from missing folders. Do not remove folder history for an unavailable drive. The existing drive-boundary and path-traversal checks still apply.\n\n`components/OperationNotifications.tsx` provides one viewport-centered notification host for both panes, viewers, and page operations. `OperationNotificationProvider` collects active notices from their existing owners. It does not own navigation, history, editor text, or locks. The host moves inside the top open dialog for modal focus access. It does not change file-row geometry.\n\nErrors precede warnings and information. Equal-priority sources retain registration order. Only one toast is visible; Next notification exposes other active failures without dismissing the current failure. There is no historical event queue. Pending notices come only from mounted owners' current state, and resolved or unmounted sources retire their notices. Optional failure keys deduplicate one failure across owners without merging different targets.\n\nToasts have a finite duration by default. `NOTICE_DURATION_MS` defines 6 seconds for information and completed results, 10 seconds for browser failures and service status, and 15 seconds for editor errors and safety warnings. Folder-recovery results use 6 seconds even though their severity is warning. Retry and Settings actions do not make a toast persistent.\n\nSet `persistent: true` only for an active upload or download with Cancel, share preparation with Cancel, or a ready-to-share decision with Share and Cancel. Sharing after confirmation uses the 6-second information timeout. These exceptions use the existing toast controls; they do not add another progress or status surface. Unsaved-change, conflict, password, and draft-recovery dialogs keep their existing decision behavior.\n\nA timer starts when its toast becomes visible, pauses during hover or keyboard focus, and does not restart for routine message updates. Expiry hides the toast without calling its `onDismiss` callback or its source's dismissal callback. Only completed informational results use `onExpire` to clear their display flags, so a later identical result can appear again. Expiry must not clear unresolved errors, cancel operations, discard drafts, or mark pairing or monitoring as healthy. Occurrence identities allow a new attempt to show the same error after expiry or dismissal. Retry retains its original target rather than following the active pane or selected row.\n\nTarget-specific notices show the message first, followed by smaller, regular-weight context on a separate line. `formatNoticeTarget` captures the connection name and full connection-relative path, including the failed file or folder. The root is `/`. Render this context with `DialogIdentifierDisplay` in its text appearance. It uses the shared grapheme-aware `abbreviatePath` algorithm to fit the visual path on one line, preserving the connection prefix and useful trailing segments where space permits. It recalculates when the available width changes. The complete value remains in the accessible name and a hover-only tooltip; shortening must not change failure identity or the Retry target. Bidirectional text is isolated. These paths do not expose the server's physical filesystem root. Global notices without a target have no context line. Known missing-file and missing-folder errors use short toast summaries without repeating the target name; inline errors and dialogs keep their detailed messages. Other error text is not rewritten.\n\nEach failure captures its own target rather than following the active pane or selected row. A recovery result identifies the original missing path, even after an accessible parent loads. If a parent fails during recovery, its failure notice identifies that parent instead. Refresh always reloads the displayed folder; it does not replay a failed navigation or native launch. Native Retry uses the item resolved by the original attempt. Backend and Companion status recovery remains available from the existing header warning menu after notification expiry or dismissal, without covering bottom file actions. The existing monitoring control and initial-folder error state also remain available. No additional inline editor warning or progress control is added when a toast expires.\n\nAn unavailable initial directory uses an unframed error state in the list area, with the original location and recovery actions. A usable previous listing, including an empty folder, remains visible after a failed target request. Loading and onboarding have their own content states. Stopped automatic updates retain a compact recovery control after toast dismissal. Backend outages have one transition notice and a persistent status control; a brief reconnection does not start another notice cycle. Expected monitor startup failures do not produce duplicate tracebacks.\n\nAutomatic parent recovery skips missing, inaccessible, and wrong-type parents within the configured root. It stops on cancellation, a newer request, pairing failure, timeout, or unavailable storage. A directory-only route replacement retains the active viewer identity and selection revision. It must not reload content, unmount a dirty editor, or acquire another edit lock.\n\n### Subscription Acknowledgements\n\nBoth WebSocket transports attach a request ID to each directory subscription. Requested and acknowledged subscriptions are separate. A reply is accepted only for the current socket, request ID, and requested location. Unsubscribe and socket cleanup retire that state and its bounded acknowledgement timer.\n\nDirectory-change events are accepted only from the socket that acknowledged the current subscription. Events before acknowledgement, after failure, or after retirement cannot refresh the pane. A successful directory refresh alone does not clear a monitor failure; the matching acknowledgement clears it.\n\nSubscription errors include the connection, path, request ID, and a safe code. Confirmed absence invalidates that exact location through the pane refresh scheduler; the fresh listing decides whether parent recovery is needed. Other subscription failures retain valid rows and show persistent Retry controls. They do not prove deletion or start an automatic subscribe/reload loop. A running monitor invalidates its deleted directory before retiring its watcher state.\n\n### Refresh Scheduling\n\nEach pane handles directory-change notifications independently. An automatic refresh keeps an already loaded physical-directory listing mounted, including an empty listing, so unchanged rows retain selection, keyboard focus, and scroll position. Initial loading and navigation without a usable snapshot still show loading feedback.\n\nNotifications don't cancel an active listing request. Instead, the pane remembers that another refresh is needed and starts one follow-up request after the active request finishes. Automatic refreshes start at most once per second. Further notifications don't move an existing deadline, so continuous writes still produce periodic updates. Navigation and unmount cancel queued work.\n\nA listing with unprocessed change notifications can remain visible, but it isn't cached as fresh. Deferred link-target metadata only updates cache entries that are still valid, so cancelling a follow-up refresh can't make an outdated snapshot reusable on return.\n\nSMB file-list subscriptions watch immediate children rather than the whole subtree. The separate backend directory-search cache retains recursive directory-name monitoring. See [SMB Change Notification and Directory Freshness](../../backend-architecture/smb-change-notification-and-directory-freshness/) for watcher ownership and lifecycle.\n\n## Progressive Quick-Bar Results\n\nPublish usable history and loaded-file results without waiting for index requests. Publish selectable records before rendering rows, merge duplicate history/index results, and reject responses for obsolete queries or sources.\n\nTreat incomplete coverage separately from request failure. Background refresh requires `search_contract_version: 1` and must stop when the query, source, visibility, or search session changes, or on terminal failure. See [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for storage and freshness rules.\n\n## URL-Driven Workspace Navigation\n\nThe URL selects the directory, pane layout, viewer, editing intent, and settings view. The file browser stays mounted under overlays. Loaded content, drafts, locks, selection, scroll, search panels, and zoom remain runtime state.\n\n| Part | Meaning |\n|---|---|\n| `/browse/smb/\u003cslug\u003e/\u003cpath\u003e` | Primary SMB pane |\n| `/browse/local/\u003cdrive-id\u003e/\u003cpath\u003e` | Primary companion-drive pane |\n| `p2=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Right pane, enabled when present |\n| `active=2` | Right pane is active |\n| `file=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Viewer target, independent of the directory and active pane |\n| `viewer=image\\|markdown\\|pdf\\|text` | Requested browser viewer |\n| `mode=edit` | Editing intent for text or Markdown |\n| `pane=2` | Right pane owns the viewer; requires a right-pane target |\n| `virtual=\u003cJSON array\u003e` | Archive member descriptor: provider ID, source archive path, member path |\n| `settings=main\\|\u003ccategory\u003e` | Settings main view or category from the shared category registry |\n\nFor example:\n\n```text\n/browse/smb/my-server/documents\n/browse/smb/my-server/documents?p2=smb%2Fother-server%2Fphotos\u0026active=2\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\u0026mode=edit\n/browse/smb/my-server/documents?settings=account\n```\n\nUse the shared parser/serializer and `URLSearchParams`, not concatenated query strings. File descriptors encode target IDs and individual path segments before query serialization. The archive provider is currently `zip`. Runtime session IDs, file contents, MIME guesses, gallery arrays, credentials, and lock capabilities never belong in navigation state.\n\n### Navigation and Dismissal\n\nOpening or closing a viewer, entering or leaving editing, changing gallery images, opening or closing settings, and changing settings categories push history entries. Repeating the same location does nothing. Pane-focus updates, invalid-descriptor recovery, failed edit acquisition, and canonicalization replace the current entry. Unrelated query parameters and authentication fragments are preserved.\n\nBack and Forward follow actual history without adding entries. Explicit Close pushes the current workspace with the dismissed layer removed, including for direct links and refreshed viewers. For example, opening a directory, opening an image, and closing it produces directory, image, and directory entries; Back reopens the image before returning to the earlier directory entry. A new action after Back discards the old Forward branch, following normal browser behavior. Close doesn't depend on opening-entry metadata or `history.length`. Settings back controls traverse observed history; without an observed predecessor they replace the URL with an in-app parent.\n\nDesktop settings and the mobile drawer are controlled by the same category descriptor. `settings=main` displays the desktop default category or the mobile category list. Resizing changes presentation without navigation. Standalone `/settings/...` routes and their aliases use the same category content and authorization checks. User Management owns its query keys through React Router, merging them with workspace parameters.\n\n### Direct Links and Recovery\n\nViewer links resolve metadata through the storage registry or content provider, without simulated file-row clicks. Resolution is cancelled when its identity changes. Missing resources show Retry and Close actions. A viewer URL never falls back to opening a native application.\n\nThe incoming URL always wins over a browser recovery snapshot. Snapshot hydration matches each pane's resource identity, clears legacy viewer state, and ignores unmatched panes. A bare `/browse` uses normal default navigation. Captured snapshots use the current canonical workspace URL and contain neither callback fragments nor edit-session tokens.\n\n### Physical File Failures\n\n`utils/apiErrors.ts` classifies nested SMB codes and top-level Companion codes. `item_not_found` means confirmed physical absence. Metadata also serves directories; `not_a_file` is reserved for operations that require a regular file. Missing connections, unavailable drive roots, archive members, pairing failures, and expired tokens remain separate. An HTTP 404 alone is not evidence that a physical file was deleted.\n\nPhysical viewer reads decode a structured binary error only when its content type is JSON and its size is bounded. An ambiguous image or PDF decode failure can make one guarded metadata request for the current resource. Existing metadata does not turn a decode failure into a deletion. Abort signals, viewer identities, and source URLs reject stale results.\n\n`services/fileRecoveryEvents.ts` carries confirmed absence to the existing pane refresh owner. Each pane invalidates the physical parent cache; only a pane still displaying that connection and parent schedules a refresh. This event does not own notices, history deletion, or editor recovery. Activation errors use pane notices. Viewer errors use the existing viewer controls, without an additional toast.\n\nRecent-file validation removes only the identified record for confirmed absence, a non-file target, an invalid stored target, or an authoritatively deleted stored connection. Item-level and connection-level access denial, generic launch failure, timeout, cancellation, pairing failure, unavailable storage, and unknown errors retain history. Publish the cross-tab change event only after actual cleanup. Recent-directory cleanup still requires an explicit missing-directory result.\n\nBrowser editor writes use ordinary create-or-overwrite behavior with the active editor lease. Save can recreate a deleted file at its original path. New lock acquisition still requires an existing regular file and must not create or truncate it. SMB requires existing parent directories; Companion uploads retain their normal parent-directory creation behavior within the available drive. A normal write can overwrite changes made at the same path; it does not compare the file with the editor baseline before writing. A failed save keeps the draft and dirty state. After a successful upload, a failed metadata refresh leaves the upload successful with an unknown modified timestamp. It must not cause an automatic repeat of the write. Native URI dispatch is not a launch acknowledgement. Do not infer later application success or failure from that handoff.\n\n### Viewer Loading and Transitions\n\nLoading feedback belongs to the selected image, PDF, text, or Markdown viewer. Workspace metadata resolution and dynamic component imports do not show an intermediate full-screen loading dialog. On an initial opening, the browser remains visible until metadata and the viewer component are available; the viewer then displays its existing content-loading feedback.\n\nOne viewer component is mounted at a time. Metadata resolution and component imports can retain the displayed resource while controls and shortcuts are suspended; Escape remains available. Once the selected component and metadata are available, that viewer owns content loading and errors. There is no hidden candidate viewer or content-readiness promotion. The editor leave guard remains the sole owner of dirty-navigation decisions.\n\nImage-gallery navigation updates the current index in the same viewer instance and publishes it to the route. The gallery keeps its local bounded cache and preloading; no image-byte cache is shared between viewer instances. An image is ready only when its decoded source exists. A failed image uses the selected image's error controls without displaying the previous image under a new filename. Explicit Retry invalidates failed local bytes and makes a fresh request. Encrypted PDFs retain the standard responsive password dialog.\n\nViewer content failures use the selected viewer's error state with Retry and Close, not a generic replacement toast. Individual loaders reject late results after a newer selection or close. There is no guarantee that a previous document remains displayed until the next document's content is ready.\n\nOne dynamic viewer host serves both panes. An explicit viewer ID, not an image's changing MIME type, controls component loading. Text and Markdown still reset resource-local state when the actual file changes; mode-only and settings-only navigation do not restart the viewer.\n\n### Editing and Router Integrity\n\nThe app uses a data router (`createBrowserRouter` and `RouterProvider`) for supported `useBlocker` behavior. One guard owner delegates resource-leaving transitions to the active text or Markdown editor when its draft is dirty, a save is pending, or a session is being acquired. Clean editor Back and Forward navigate directly, avoiding the history reversal required by a blocked browser navigation. Cancel keeps the draft and lock; successful Save or Discard continues the original transition; failed Save keeps the editor open. Changes that retain the same edited resource and mode don't discard its draft. Dirty drafts also register `beforeunload` protection.\n\nEdit bookmarks and history navigation back into editing acquire a fresh edit session after content and permission checks. Navigating away during acquisition invalidates the attempt and releases any late lock. Leaving editing releases its session once. The outgoing editor is read-only during cleanup, and re-entry waits for that cleanup to finish so an old release can't clear a new session. History restores navigation intent, not old file contents, discarded drafts, or saved locks. An edit URL doesn't grant permission.\n\nFull page reloads, including F5 and the update prompt, can resume the same edit lock. The shared storage edit-session layer keeps lock credentials separately in tab-scoped session storage, keyed by user, connection, and file. On reload it validates those credentials with a heartbeat before reusing them. Only a structured lost-lock response permits fresh acquisition; network and permission failures don't trigger replacement. Credentials follow replacement locks and are removed on successful release or logout. Unsaved text still uses the existing draft-recovery flow.\n\nRecovery requires session storage and the browser Web Locks API, available in secure contexts such as HTTPS and localhost. An exclusive Web Lock prevents another tab from using copied recovery credentials, even if that tab reloads. Without those capabilities, editing still works, but a reload may need to wait for the abandoned server lock to expire. Fresh navigations and history entries don't resume saved credentials, and no credentials appear in the URL or workspace recovery snapshot.\n\nUse router navigation for all mounted-route URL writes, including authentication fragment cleanup. `useRemoveLocationFragment` replaces the entry, removes only consumed fragment keys, and preserves the full query and application state. Never clear router-managed history state with `replaceState(null, ...)`: doing so can disable POP blocking.\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.8": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.9": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "1.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "2.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/routing.ts` | parses and serializes typed directory, viewer, editor, and settings locations |\n| `pages/FileBrowser/useWorkspaceNavigation.ts` | resolves viewer targets and owns workspace navigation and safe overlay return entries |\n| `hooks/useRoutedViewerEditing.tsx` | connects the active editor's existing confirmation dialog to React Router navigation blocking |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## Real-Time Directory Refresh\n\n### Directory Navigation Failures\n\nPhysical directory navigation has a pending target and a displayed location. Load the target through the content provider before committing its connection, path, rows, and route. A failed navigation keeps the previous displayed location, selection, and scroll state. Request cancellation and location guards reject late responses, including responses from automatic parent recovery.\n\nOnly successfully loaded physical directories become file-list subscription targets. Missing initial locations and deleted current directories recover to an accessible parent, or clear stale rows and keep recovery controls visible. Canonical recovery replaces the affected route; it does not use browser Back or change the other pane.\n\nThe SMB storage boundary translates named missing-name, missing-parent, access-denied, and wrong-type statuses into typed storage errors. Directory listing returns a structured API code and a safe message. Only a confirmed `directory_not_found` result permits stale history and directory-index removal. A connection-level HTTP 404 is not proof that a folder was deleted.\n\nCompanion directory listings use the same `directory_not_found`, `directory_access_denied`, `not_a_directory`, and `directory_unavailable` codes. Companion responses put `code` beside the safe `detail` string; SMB responses put the code inside `detail`. The pane accepts both formats. Local path validation and directory reads use the directory error mapper, while unavailable drive roots remain separate from missing folders. Do not remove folder history for an unavailable drive. The existing drive-boundary and path-traversal checks still apply.\n\n`components/OperationNotifications.tsx` provides one viewport-centered notification host for both panes, viewers, and page operations. `OperationNotificationProvider` collects active notices from their existing owners. It does not own navigation, history, editor text, or locks. The host moves inside the top open dialog for modal focus access. It does not change file-row geometry.\n\nErrors precede warnings and information. Equal-priority sources retain registration order. Only one toast is visible; Next notification exposes other active failures without dismissing the current failure. There is no historical event queue. Pending notices come only from mounted owners' current state, and resolved or unmounted sources retire their notices. Optional failure keys deduplicate one failure across owners without merging different targets.\n\nToasts have a finite duration by default. `NOTICE_DURATION_MS` defines 6 seconds for information and completed results, 10 seconds for browser failures and service status, and 15 seconds for editor errors and safety warnings. Folder-recovery results use 6 seconds even though their severity is warning. Retry and Settings actions do not make a toast persistent.\n\nSet `persistent: true` only for an active upload or download with Cancel, share preparation with Cancel, or a ready-to-share decision with Share and Cancel. Sharing after confirmation uses the 6-second information timeout. These exceptions use the existing toast controls; they do not add another progress or status surface. Unsaved-change, conflict, password, and draft-recovery dialogs keep their existing decision behavior.\n\nA timer starts when its toast becomes visible, pauses during hover or keyboard focus, and does not restart for routine message updates. Expiry hides the toast without calling its `onDismiss` callback or its source's dismissal callback. Only completed informational results use `onExpire` to clear their display flags, so a later identical result can appear again. Expiry must not clear unresolved errors, cancel operations, discard drafts, or mark pairing or monitoring as healthy. Occurrence identities allow a new attempt to show the same error after expiry or dismissal. Retry retains its original target rather than following the active pane or selected row.\n\nTarget-specific notices show the message first, followed by smaller, regular-weight context on a separate line. `formatNoticeTarget` captures the connection name and full connection-relative path, including the failed file or folder. The root is `/`. Render this context with `DialogIdentifierDisplay` in its text appearance. It uses the shared grapheme-aware `abbreviatePath` algorithm to fit the visual path on one line, preserving the connection prefix and useful trailing segments where space permits. It recalculates when the available width changes. The complete value remains in the accessible name and a hover-only tooltip; shortening must not change failure identity or the Retry target. Bidirectional text is isolated. These paths do not expose the server's physical filesystem root. Global notices without a target have no context line. Known missing-file and missing-folder errors use short toast summaries without repeating the target name; inline errors and dialogs keep their detailed messages. Other error text is not rewritten.\n\nEach failure captures its own target rather than following the active pane or selected row. A recovery result identifies the original missing path, even after an accessible parent loads. If a parent fails during recovery, its failure notice identifies that parent instead. Refresh always reloads the displayed folder; it does not replay a failed navigation or native launch. Native Retry uses the item resolved by the original attempt. Backend and Companion status recovery remains available from the existing header warning menu after notification expiry or dismissal, without covering bottom file actions. The existing monitoring control and initial-folder error state also remain available. No additional inline editor warning or progress control is added when a toast expires.\n\nAn unavailable initial directory uses an unframed error state in the list area, with the original location and recovery actions. A usable previous listing, including an empty folder, remains visible after a failed target request. Loading and onboarding have their own content states. Stopped automatic updates retain a compact recovery control after toast dismissal. Backend outages have one transition notice and a persistent status control; a brief reconnection does not start another notice cycle. Expected monitor startup failures do not produce duplicate tracebacks.\n\nAutomatic parent recovery skips missing, inaccessible, and wrong-type parents within the configured root. It stops on cancellation, a newer request, pairing failure, timeout, or unavailable storage. A directory-only route replacement retains the active viewer identity and selection revision. It must not reload content, unmount a dirty editor, or acquire another edit lock.\n\n### Subscription Acknowledgements\n\nBoth WebSocket transports attach a request ID to each directory subscription. Requested and acknowledged subscriptions are separate. A reply is accepted only for the current socket, request ID, and requested location. Unsubscribe and socket cleanup retire that state and its bounded acknowledgement timer.\n\nDirectory-change events are accepted only from the socket that acknowledged the current subscription. Events before acknowledgement, after failure, or after retirement cannot refresh the pane. A successful directory refresh alone does not clear a monitor failure; the matching acknowledgement clears it.\n\nSubscription errors include the connection, path, request ID, and a safe code. Confirmed absence invalidates that exact location through the pane refresh scheduler; the fresh listing decides whether parent recovery is needed. Other subscription failures retain valid rows and show persistent Retry controls. They do not prove deletion or start an automatic subscribe/reload loop. A running monitor invalidates its deleted directory before retiring its watcher state.\n\n### Refresh Scheduling\n\nEach pane handles directory-change notifications independently. An automatic refresh keeps an already loaded physical-directory listing mounted, including an empty listing, so unchanged rows retain selection, keyboard focus, and scroll position. Initial loading and navigation without a usable snapshot still show loading feedback.\n\nNotifications don't cancel an active listing request. Instead, the pane remembers that another refresh is needed and starts one follow-up request after the active request finishes. Automatic refreshes start at most once per second. Further notifications don't move an existing deadline, so continuous writes still produce periodic updates. Navigation and unmount cancel queued work.\n\nA listing with unprocessed change notifications can remain visible, but it isn't cached as fresh. Deferred link-target metadata only updates cache entries that are still valid, so cancelling a follow-up refresh can't make an outdated snapshot reusable on return.\n\nSMB file-list subscriptions watch immediate children rather than the whole subtree. The separate backend directory-search cache retains recursive directory-name monitoring. See [SMB Change Notification and Directory Freshness](../../backend-architecture/smb-change-notification-and-directory-freshness/) for watcher ownership and lifecycle.\n\n## Progressive Quick-Bar Results\n\nPublish usable history and loaded-file results without waiting for index requests. Publish selectable records before rendering rows, merge duplicate history/index results, and reject responses for obsolete queries or sources.\n\nTreat incomplete coverage separately from request failure. Background refresh requires `search_contract_version: 1` and must stop when the query, source, visibility, or search session changes, or on terminal failure. See [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for storage and freshness rules.\n\n## URL-Driven Workspace Navigation\n\nThe URL selects the directory, pane layout, viewer, editing intent, and settings view. The file browser stays mounted under overlays. Loaded content, drafts, locks, selection, scroll, search panels, and zoom remain runtime state.\n\n| Part | Meaning |\n|---|---|\n| `/browse/smb/\u003cslug\u003e/\u003cpath\u003e` | Primary SMB pane |\n| `/browse/local/\u003cdrive-id\u003e/\u003cpath\u003e` | Primary companion-drive pane |\n| `p2=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Right pane, enabled when present |\n| `active=2` | Right pane is active |\n| `file=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Viewer target, independent of the directory and active pane |\n| `viewer=image\\|markdown\\|pdf\\|text` | Requested browser viewer |\n| `mode=edit` | Editing intent for text or Markdown |\n| `pane=2` | Right pane owns the viewer; requires a right-pane target |\n| `virtual=\u003cJSON array\u003e` | Archive member descriptor: provider ID, source archive path, member path |\n| `settings=main\\|\u003ccategory\u003e` | Settings main view or category from the shared category registry |\n\nFor example:\n\n```text\n/browse/smb/my-server/documents\n/browse/smb/my-server/documents?p2=smb%2Fother-server%2Fphotos\u0026active=2\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\u0026mode=edit\n/browse/smb/my-server/documents?settings=account\n```\n\nUse the shared parser/serializer and `URLSearchParams`, not concatenated query strings. File descriptors encode target IDs and individual path segments before query serialization. The archive provider is currently `zip`. Runtime session IDs, file contents, MIME guesses, gallery arrays, credentials, and lock capabilities never belong in navigation state.\n\n### Navigation and Dismissal\n\nOpening or closing a viewer, entering or leaving editing, changing gallery images, opening or closing settings, and changing settings categories push history entries. Repeating the same location does nothing. Pane-focus updates, invalid-descriptor recovery, failed edit acquisition, and canonicalization replace the current entry. Unrelated query parameters and authentication fragments are preserved.\n\nBack and Forward follow actual history without adding entries. Explicit Close pushes the current workspace with the dismissed layer removed, including for direct links and refreshed viewers. For example, opening a directory, opening an image, and closing it produces directory, image, and directory entries; Back reopens the image before returning to the earlier directory entry. A new action after Back discards the old Forward branch, following normal browser behavior. Close doesn't depend on opening-entry metadata or `history.length`. Settings back controls traverse observed history; without an observed predecessor they replace the URL with an in-app parent.\n\nDesktop settings and the mobile drawer are controlled by the same category descriptor. `settings=main` displays the desktop default category or the mobile category list. Resizing changes presentation without navigation. Standalone `/settings/...` routes and their aliases use the same category content and authorization checks. User Management owns its query keys through React Router, merging them with workspace parameters.\n\n### Direct Links and Recovery\n\nViewer links resolve metadata through the storage registry or content provider, without simulated file-row clicks. Resolution is cancelled when its identity changes. Missing resources show Retry and Close actions. A viewer URL never falls back to opening a native application.\n\nThe incoming URL always wins over a browser recovery snapshot. Snapshot hydration matches each pane's resource identity, clears legacy viewer state, and ignores unmatched panes. A bare `/browse` uses normal default navigation. Captured snapshots use the current canonical workspace URL and contain neither callback fragments nor edit-session tokens.\n\n### Physical File Failures\n\n`utils/apiErrors.ts` classifies nested SMB codes and top-level Companion codes. `item_not_found` means confirmed physical absence. Metadata also serves directories; `not_a_file` is reserved for operations that require a regular file. Missing connections, unavailable drive roots, archive members, pairing failures, and expired tokens remain separate. An HTTP 404 alone is not evidence that a physical file was deleted.\n\nPhysical viewer reads decode a structured binary error only when its content type is JSON and its size is bounded. An ambiguous image or PDF decode failure can make one guarded metadata request for the current resource. Existing metadata does not turn a decode failure into a deletion. Abort signals, viewer identities, and source URLs reject stale results.\n\n`services/fileRecoveryEvents.ts` carries confirmed absence to the existing pane refresh owner. Each pane invalidates the physical parent cache; only a pane still displaying that connection and parent schedules a refresh. This event does not own notices, history deletion, or editor recovery. Activation errors use pane notices. Viewer errors use the existing viewer controls, without an additional toast.\n\nRecent-file validation removes only the identified record for confirmed absence, a non-file target, an invalid stored target, or an authoritatively deleted stored connection. Item-level and connection-level access denial, generic launch failure, timeout, cancellation, pairing failure, unavailable storage, and unknown errors retain history. Publish the cross-tab change event only after actual cleanup. Recent-directory cleanup still requires an explicit missing-directory result.\n\nBrowser editor writes use ordinary create-or-overwrite behavior with the active editor lease. Save can recreate a deleted file at its original path. New lock acquisition still requires an existing regular file and must not create or truncate it. SMB requires existing parent directories; Companion uploads retain their normal parent-directory creation behavior within the available drive. A normal write can overwrite changes made at the same path; it does not compare the file with the editor baseline before writing. A failed save keeps the draft and dirty state. After a successful upload, a failed metadata refresh leaves the upload successful with an unknown modified timestamp. It must not cause an automatic repeat of the write. Native URI dispatch is not a launch acknowledgement. Do not infer later application success or failure from that handoff.\n\n### Viewer Loading and Transitions\n\nLoading feedback belongs to the selected image, PDF, text, or Markdown viewer. Workspace metadata resolution and dynamic component imports do not show an intermediate full-screen loading dialog. On an initial opening, the browser remains visible until metadata and the viewer component are available; the viewer then displays its existing content-loading feedback.\n\nOne viewer component is mounted at a time. Metadata resolution and component imports can retain the displayed resource while controls and shortcuts are suspended; Escape remains available. Once the selected component and metadata are available, that viewer owns content loading and errors. There is no hidden candidate viewer or content-readiness promotion. The editor leave guard remains the sole owner of dirty-navigation decisions.\n\nImage-gallery navigation updates the current index in the same viewer instance and publishes it to the route. The gallery keeps its local bounded cache and preloading; no image-byte cache is shared between viewer instances. An image is ready only when its decoded source exists. A failed image uses the selected image's error controls without displaying the previous image under a new filename. Explicit Retry invalidates failed local bytes and makes a fresh request. Encrypted PDFs retain the standard responsive password dialog.\n\nViewer content failures use the selected viewer's error state with Retry and Close, not a generic replacement toast. Individual loaders reject late results after a newer selection or close. There is no guarantee that a previous document remains displayed until the next document's content is ready.\n\nOne dynamic viewer host serves both panes. An explicit viewer ID, not an image's changing MIME type, controls component loading. Text and Markdown still reset resource-local state when the actual file changes; mode-only and settings-only navigation do not restart the viewer.\n\n### Editing and Router Integrity\n\nThe app uses a data router (`createBrowserRouter` and `RouterProvider`) for supported `useBlocker` behavior. One guard owner delegates resource-leaving transitions to the active text or Markdown editor when its draft is dirty, a save is pending, or a session is being acquired. Clean editor Back and Forward navigate directly, avoiding the history reversal required by a blocked browser navigation. Cancel keeps the draft and lock; successful Save or Discard continues the original transition; failed Save keeps the editor open. Changes that retain the same edited resource and mode don't discard its draft. Dirty drafts also register `beforeunload` protection.\n\nEdit bookmarks and history navigation back into editing acquire a fresh edit session after content and permission checks. Navigating away during acquisition invalidates the attempt and releases any late lock. Leaving editing releases its session once. The outgoing editor is read-only during cleanup, and re-entry waits for that cleanup to finish so an old release can't clear a new session. History restores navigation intent, not old file contents, discarded drafts, or saved locks. An edit URL doesn't grant permission.\n\nFull page reloads, including F5 and the update prompt, can resume the same edit lock. The shared storage edit-session layer keeps lock credentials separately in tab-scoped session storage, keyed by user, connection, and file. On reload it validates those credentials with a heartbeat before reusing them. Only a structured lost-lock response permits fresh acquisition; network and permission failures don't trigger replacement. Credentials follow replacement locks and are removed on successful release or logout. Unsaved text still uses the existing draft-recovery flow.\n\nRecovery requires session storage and the browser Web Locks API, available in secure contexts such as HTTPS and localhost. An exclusive Web Lock prevents another tab from using copied recovery credentials, even if that tab reloads. Without those capabilities, editing still works, but a reload may need to wait for the abandoned server lock to expire. Fresh navigations and history entries don't resume saved credentials, and no credentials appear in the URL or workspace recovery snapshot.\n\nUse router navigation for all mounted-route URL writes, including authentication fragment cleanup. `useRemoveLocationFragment` replaces the entry, removes only consumed fragment keys, and preserves the full query and application state. Never clear router-managed history state with `replaceState(null, ...)`: doing so can disable POP blocking.\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/keyboard-shortcuts-and-command-model", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "keyboard-shortcuts-and-command-model", "title": "Keyboard Shortcuts And Command Model", "path": "developer-guide/frontend-architecture/keyboard-shortcuts-and-command-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 14, "diff_removed": 6}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 2, "diff_removed": 63}}, "content_versions": {"0.7": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.8": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.9": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "1.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "2.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\n`browser.focusLeftPane` and `browser.focusRightPane` remain available through command search without keyboard bindings. Do not register `Ctrl+1`, `Ctrl+2`, or their Meta equivalents for pane focus. These keys remain available to the browser. The right-pane command also opens dual-pane mode when only one pane is visible.\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system."}, "page_contents": {"0.7": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.8": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.9": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "1.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "2.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\n`browser.focusLeftPane` and `browser.focusRightPane` remain available through command search without keyboard bindings. Do not register `Ctrl+1`, `Ctrl+2`, or their Meta equivalents for pane focus. These keys remain available to the browser. The right-pane command also opens dual-pane mode when only one pane is visible.\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "viewer-architecture-and-preview-contracts", "title": "Viewer Architecture And Preview Contracts", "path": "developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 211, "diff_removed": 10}}, "content_versions": {"0.7": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.8": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.9": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "1.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "2.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must agree on image formats, conversion requirements, and MIME types used for dedicated viewers\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/fileLanguages.ts` | shared CodeMirror language catalogue, filename matching, and additional plain-text extensions used by highlighting and default text opening |\n| `frontend/src/utils/FileTypeRegistry.ts` | dedicated viewer mappings and MIME/presentation metadata; derives text-editor support from shared filename recognition |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nDedicated formats such as images require backend and frontend agreement. Text-file recognition instead uses `fileLanguages.ts`: both highlighting and default text opening consume the same CodeMirror catalogue. Language metadata doesn't load a grammar or import the highlighting core into the file browser.\n\nExplicit image, PDF, and Markdown viewers take precedence over extension-based text recognition. A recognized, non-generic MIME type with a viewer mapping takes precedence over the filename; empty MIME types, `application/octet-stream`, and `text/plain` fall back to filename recognition. Saved viewer preferences override the default selection. Unknown files still use the viewer picker unless a MIME mapping or saved preference selects a viewer.\n\nAll file viewers and editors use `useViewerDocumentTitle` to set the browser tab title to the active filename, including its extension. Image navigation updates the title to the active image. Native print events temporarily remove the final extension so browsers can suggest a clean PDF filename. The Markdown Print action uses the hook's print callback to prepare the title before opening the dialog and restore it after a print failure. Successful calls retain the short title until `afterprint`; `window.print()` can return before the print dialog closes. Closing the workspace restores the previous title unless another owner has changed it.\n\n## Unified Text Editor\n\n`TextEditor.tsx` owns the text destination and reuses `TextCodeEditor` for writable and read-only content. There isn't a separate text-viewer component or an Edit action. The public `viewer=text` identifier, viewer preferences, settings, and recovery-draft keys remain compatible. Text routes accept absent, `view`, and `edit` modes as the same destination; canonical URLs omit `mode` without adding a history entry or dropping fragments. Markdown still uses its existing preview/edit route modes.\n\nOpening an eligible text file automatically calls `beginViewerTextEdit`. The editor stays read-only until acquisition succeeds and a fresh content read establishes the baseline. Archive members, read-only connections, and oversized files don't acquire sessions. Storage boundaries distinguish contention, denied permissions, unsupported editing, and temporary unavailability. SMB's acquisition request opts into a non-mutating per-file write probe; Companion also checks an existing file with read/write open and no creation or truncation.\n\nAcquisition feedback appears after 200 ms as a small spinner beside the filename, in a fixed-size toolbar slot. Fast acquisitions show no progress message, and slower ones don't move the document. Completion, navigation, and unmount cancel pending feedback without delaying readiness. Access failures remain immediate; related error details and the read-only reason share one notice with Retry where supported.\n\nAcquisition uses an activation generation to release obsolete results, and a pending release completes before another acquisition starts. Confirmed lock loss or revoked access freezes mutations and retains the draft; a transient heartbeat failure shows a warning. Retry is explicit, not an acquisition loop. A fresh baseline that differs from a retained draft's original baseline requires a conflict decision before editing resumes. Choosing the draft doesn't save it.\n\nText and Markdown saves pass `reacquireExpiredLock: false`; they must not silently reacquire an expired lock and overwrite a changed file. Save acknowledges only the captured revision, preserving newer edits as dirty. The routed leave guard protects dirty navigation and pending operations. Text Close goes directly to the file list after release, and Discard commits a clean state before navigation so the guard doesn't prompt twice.\n\nSave from a valid active session can recreate a file deleted at the original path. It can also overwrite changes made at that path; it does not detect replacement files. Failed writes retain the draft. The dynamic host mounts one viewer, not a hidden candidate alongside the current document. Each viewer owns its load and error state; the image gallery reuses only its own local cache.\n\nRead-only disables typing, Save, and Replace, not Find, selection, copying, wrapping, download, or sharing. Recovery is resolved before automatic activation. Keep regressions for late acquisition, Strict Mode, read-only and conflict states, history navigation, and Markdown's separate lifecycle when changing this shared path.\n\n## Shared Viewer Notifications\n\n`ViewerNotifications.tsx` reuses the application notification host, shared edit-lock message mapping, and delayed acquisition indicator for text and Markdown. There is no viewer-corner or pane-local toast host in the file browser. Markdown retains its preview/edit lifecycle, but uses the same lock/read-only notification, filename badge, explicit Retry action, and retained-draft conflict decision. Lock release completes before another acquisition starts; obsolete acquisition results are released without publishing errors.\n\nEach viewer supplies active notices with stable IDs, severity, and operation occurrence numbers. One host displays one bottom-center toast across both panes and all viewer and page operations, prioritizing errors over warnings and information. Next notification exposes another pending condition. Dismissed heartbeat and draft-storage conditions stay dismissed until resolution or a changed condition. A new operation failure can notify again even when its message is unchanged. Resolved notices leave the active set, and source identities isolate dismissal state between files. Moving the host into a modal does not reset dismissal state.\n\nAll Text and Markdown editor toasts expire after 15 seconds, including informational lock notices, edit and save errors, print errors, heartbeat warnings, and draft-storage warnings. Hover or keyboard focus pauses expiry. Expiry hides only the notification; it does not clear the error, release a lock, discard a draft, or change the edit session. There is no additional inline warning after expiry. Existing editor controls and unsaved-change safeguards remain available. Toasts don't take focus or change document geometry. Recovery and unsaved-changes dialogs retain their own failure notices and suppress viewer toasts while open. Document-load failures, file-size limits, search validation, and editor-load/crash recovery remain in context rather than moving into the toast queue.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nPhysical streams read their first chunk before sending response headers. An initial read failure can therefore return a safe structured error. A later read failure terminates the stream and closes the backend; it cannot replace an already committed HTTP response with JSON. PDF derivative preparation reads its source before returning bytes, so a source failure during that buffered read can still use the structured error boundary. Native-download intent redemption uses the same prepared-stream boundary.\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### PDF Loading And Password Cancellation\n\nThe PDF viewer keeps the document hidden and its controls disabled until the active page's canvas has rendered. The loading indicator and text appear only after 500 ms. A fast load shows neither. Each new document, retry, or compatibility attempt starts a new feedback delay. Readiness does not wait for text extraction or a minimum indicator display time.\n\nEscape, Cancel, and the mobile back action in the password dialog cancel the current PDF load. Cancellation clears the password, unmounts the document to destroy its PDF.js loading task, releases its blob URL, and shows a notice with Retry. It does not submit an empty or null password, and it does not request compatibility processing. Downloading the original remains available through the viewer's existing download action. Only an explicit retry can start a new password request after cancellation.\n\nPassword callbacks belong to one load session. The viewer ignores callbacks from canceled or replaced sessions. An incorrect password can request another attempt within the same active session.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation. Its text-layer markers use `frontend/src/utils/domTextSearch.ts`.\n- Rendered Markdown uses a preview-owned session in `frontend/src/utils/viewportDomTextSearch.ts`. It reuses the DOM index and matcher from `domTextSearch.ts`, preserving rendered-text boundaries, cross-inline matches and exact code whitespace.\n- Markdown edit mode doesn't reuse the rendered-view DOM search implementation. It bridges the same outer toolbar UI into the editor-specific search state and commands instead.\n\nThe Markdown preview separates logical matches from their presentation. It retains exact match positions and text-node mappings, but paints at most 1,000 viewport search ranges plus one active-match range through CSS Highlights. Search doesn't insert markers, split text nodes or replace preview content. Navigation resolves the destination directly from the index and scrolls the content viewport, including for off-screen matches.\n\nEach preview generation owns its search session. Query changes reuse the unchanged DOM index; text replacement or character-data changes invalidate it. Syntax painting and theme-variable changes don't invalidate it. Scroll, resize, image loading and font readiness refresh presentation without matching the document again. Disposing the preview removes its highlights, style, observers, listeners, cached text and pending animation frame. PDF search remains independent.\n\nDOM capture collects text chunks and joins them once, preserving numeric offsets and block separators without repeatedly flattening the growing source. Syntax publication separately caps its viewport ranges and clips horizontally overflowing unwrapped code to visible columns. Both search and syntax skip vertical character-range lookup when the owning text box is wholly inside the viewport; partially clipped boxes retain exact boundary lookup. Horizontal clipping is independent of that fast path: the left lookup can stop at the first character, and the right lookup reuses the exact left boundary as its lower bound. Disjoint horizontal clips produce no ranges. These optimizations don't estimate character widths or cache geometry. Nested code-block scrolling refreshes syntax and search ranges without changing the source or search index.\n\nSearch highlight colors inherit the preview's scoped theme variables. Browsers without CSS Highlights retain counts and indexed navigation without visual search highlighting; the viewer logs that limitation rather than falling back to whole-document marker insertion. Browser support and whole-viewer performance acceptance remain separate rollout gates. Cached indexing doesn't guarantee responsive capture or rendering for arbitrarily large documents.\n\nUse the existing production-viewer check in `frontend/e2e/markdown-viewer.spec.ts` to attribute performance within the ReactMarkdown path. Its User Timing entries separate preview-search lookup, geometry, scrolling and publication from syntax mapping, geometry, range construction and publication. Geometry reads may force layout; registry calls can include native browser work, but don't necessarily include deferred painting. Worker round trips include transfer and acknowledgements, not just parsing. Source-response, DOM-commit-observer and frame milestones narrow initial-load costs without claiming isolated React CPU or hardware input-to-visible-paint latency. Functional passes don't establish the responsiveness budgets.\n\nInitial-load Markdown normalization uses the shared helper in `frontend/src/utils/markdownCodePreparation.ts`. Documents of at most 4,096 UTF-16 units run the existing canonical normalizer directly, avoiding worker startup and transport for small notes. This bounded path returns the same canonical text and prepared MDAST; it doesn't skip normalization or change rendering. The size limit lives in the shared preparation protocol. Larger documents each own a preparation worker and transfer source, canonical text and an equivalent canonical MDAST in acknowledged, bounded chunks. Tree batches contain at most 512 records and 16,384 string UTF-16 units; individual field pieces are at most 2,048 units. Numeric/flag/position metadata is validated separately, and large text and table alignment fields use the chunk channel instead of content limits. Host acknowledgements yield between tree batches. Success, cancellation, decode failure and timeout terminate the worker; aborted loads can't publish content. Worker failures use the existing load-error path without a synchronous retry, and local preparation failures aren't reported as server overload. The pre-app capability gate requires a callable Web Worker API and otherwise shows the existing unsupported-browser screen without importing the app. The helper retains defensive synchronous normalization with a diagnostic for larger documents when workers are unavailable, but Worker-less app operation isn't supported. API presence doesn't guarantee successful worker construction or execution; existing startup, timeout, crash and decode-error handling remains necessary. The shared protocol is DOM-free. Vite's shared resolver aliases the character decoder to its non-DOM implementation before dependency optimization, so development and production workers use the same implementation. A worker-build-only resolver isn't sufficient for development's prebundled dependencies.\n\nReactMarkdown remains the only application whole-document renderer in every build mode. Its parser hook reuses a defensive clone of the prepared tree only when the tree matches the preview generation's exact source. All normal remark transforms, GFM, table-cell break handling, safe URL/raw HTML behavior and React rendering remain in that path. Cloning prevents those transforms from mutating the retained canonical tree. A successful Save that changes the source releases the superseded tree; edited content without a matching tree uses the normal parser.\n\nRendered Markdown sources of at least 50,000 UTF-16 units use `ProgressiveMarkdown` to append the existing pipeline's fully transformed output. Document-wide references, headings and GFM are resolved once before staging. Chunks aren't parsed as independent Markdown documents. Ordinary sources keep their immediate rendering path. Staged batches use the same ReactMarkdown rendering and safe-link/raw-HTML handling, with at most 1,024 structural nodes or 8,192 text units. Oversized tables, containers and code blocks are subdivided internally, preserving one native table or code block rather than splitting it into separate documents. Already-published nodes aren't replaced by later appends.\n\nThe viewer targets two viewport heights for the initial fill, then yields. Later frames use the 4 ms elapsed-work target without a height limit or repeated per-batch geometry reads. Each frame commits at most four batches, checking elapsed time after every commit to bound work accumulated before native layout. Neither the fill target nor these limits guarantee a maximum task duration: whole-document cloning/transforms, a single commit and native layout remain synchronous. Visible pages use animation frames; hidden pages use timers so completion doesn't wait indefinitely for a frame. Source or rendering-configuration changes and disposal cancel the old publication owner; a restarted generation resets document readiness. A 200 ms delayed, accessible loading indicator disappears immediately on completion and respects reduced motion.\n\nReading published text and closing the viewer remain available during progressive loading. Document search/counts, editing, heading-link navigation and toolbar printing wait for complete publication; syntax painting and DOM search indexing also wait. Browser-menu printing while loading shows a loading notice instead of partial document content. Once complete, normal native selection, search, links and print behavior apply. These controls prevent partial results from being presented as complete; they don't promise that synchronous preparation can never block input.\n\nMarkdown editing reuses the preparation worker for full-document canonical normalization when the editor source contains `\u003cbr`. The existing no-`\u003cbr` typing path still publishes immediately without normalization. If both the original baseline and edited document contain possible table syntax, a background preservation-only job compares their tables without changing that typing normalization policy. Identical sources or documents without a pipe character need no table comparison. Each editor owns at most one active job and one replaceable latest request. Only the current source, baseline, policy and generation can satisfy a prepared snapshot; obsolete success, failure and diagnostic messages are ignored. Worker acknowledgements never replace the native CodeMirror document, recreate table-cell editors or change transaction history. Pending table/IME publication and worker preparation keep the viewer dirty independently of canonical draft publication. External source changes and unmount dispose the old owner and its workers; a baseline change invalidates unmatched prepared bytes.\n\nToolbar Save takes focus before its click handler captures selection. The rich editor therefore remembers the active nested table cell on native focus entry and departure, and refreshes that snapshot when selection is explicitly preserved inside the editor. Stay-edit Save restores the same connected cell within the current root instead of focusing the root and triggering native table-widget reconstruction. If the cell document changed while Save was pending, restoration keeps its newer native selection rather than replaying old offsets. Returning to root-text editing, replacing the external document and unmounting clear the remembered cell; disconnected or replaced cells use the existing root-selection fallback. This doesn't change native transactions, history grouping or composition handling. Production checks require retained cell identity/focus after Save, continued typing, and native undo/redo; these functional checks don't establish responsiveness acceptance.\n\nAsync snapshot capture flushes table/IME publication and worker preparation within the existing transition deadline. It requires full-document normalization even after the typing fast path, so Save retains list, escape and table canonicalization. The same worker performs the unchanged AST-aware table comparison against the exact original baseline, preserving original source for semantically unchanged tables. Source and baseline transfer sequentially in acknowledged chunks of at most 16,384 UTF-16 units, with generation and sequence validation; result chunks retain the same bound. Edit preparation doesn't request a preview tree, whose offsets would no longer match preserved source. Save consumes immutable, complete source-preserving snapshot bytes; repeated serialization returns the captured string without parsing. A successful write acknowledges only its snapshot: newer pending edits stay dirty, and an unavailable newer snapshot doesn't turn the completed write into a failure. Worker failure preserves editing and dirty content; a subsequent explicit async snapshot request can retry, but failures never trigger a synchronous parsing fallback or an automatic retry loop.\n\nSynchronous snapshot capture and canonical getters reject pending or failed worker preparation, including an unmatched source-preservation baseline, rather than returning an older revision as current. Recovery retains its synchronous pagehide/pre-sign-in attempts, debounce and limits; failed capture logs the failure and shows the existing recovery warning. It doesn't mark content saved. Native text sharing is unavailable while publication is pending and reads a complete snapshot when ready. Worker-side normalization and source preservation don't establish whole-viewer timing or resource acceptance; native table editing, layout and preview reconstruction remain separately measured costs.\n\nThe bounded `sambee:edit-preparation:*` entries separate queue wait, worker startup/first acknowledgement, source and baseline transfers, run-to-first-result, result delivery, total transport/job time and complete async snapshot flush. Numeric metadata records generation, source/baseline lengths, policy, chunk counts and whether a completed job is current or obsolete; it contains no source text. Transport completion also reports worker normalization and source-preservation durations separately. Host intervals include event-loop scheduling and acknowledgement delays, so startup isn't isolated worker boot time and transfer isn't pure wire time. Worker durations aren't main-thread CPU, and nested intervals mustn't be added to their enclosing job or snapshot flush. Each stage retains only its latest entry; the existing test observer collects individual samples. Use these measurements to distinguish Save wait from the native table/focus work that can follow write acknowledgement, not to infer a faster Save or passing keyboard/paint budgets from worker offload alone.\n\nThe bounded `sambee:preview-preparation:*` entries separate asynchronous decode elapsed time, load normalization, tree cloning, code-block collection and ReactMarkdown transforms. For worker-backed loads, `load-normalization-elapsed` includes worker startup, transfer, work, host tree assembly, acknowledgements and scheduling, not main-thread CPU time. For small notes, it measures direct canonical normalization and prepared-tree creation. `render-prepared-tree` measures the defensive clone; `render-parse` measures normal parsing when no matching tree is available. The initial-load production matrix requires the clone stage and rejects synchronous `render-parse` and standalone `collection-parse` stages. Live syntax request collection walks the renderer's existing tree; it doesn't parse source again or change markup. The `collection-walk` interval is included in `render-transform`, not additional time to sum. Each generation publishes its ordered requests after DOM commit, before the passive syntax preparation effect, which snapshots them and retains cancellation and stale-generation guards.\n\nThe HAST-ready-to-layout-effect interval includes element construction, reconciliation, commit and scheduling, not just React CPU or paint. Entries contain no source text; each stage retains its latest measurement while the browser test observer collects individual samples. Normalization reuses its parsed tree when canonicalization leaves the source unchanged and reparses in the same preparation path when edits change source offsets. Tree reuse doesn't close responsiveness, retained-memory, syntax-completion or native interaction acceptance.\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Single-Renderer Acceptance\n\nThe retained whole-document viewer integration and its special build-mode selection have been removed. Don't reconnect the historical publisher or add a second renderer to finish shared highlighting. Reuse ReactMarkdown, its parsed-tree code collection, the existing workers and viewport CSS highlights. Standalone renderer proofs are historical research, not application acceptance or a delivery dependency.\n\nRun `npm run build`, then `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production syntax publication' --workers=1 --repeat-each=3` from `frontend/`. The existing matrix uses the approved demo connection and unchanged dense, near-safeguard, host-envelope, many-block and long-line fixtures in Chromium and Firefox at desktop and narrow widths. Add `PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-reactmarkdown-baseline.json` and `--reporter=json` to retain structured reports without npm's console preamble. Each fixture attaches `viewer-timing-budgets.json`, with observed values, numeric targets, pass/fail results and criteria that remain unmeasured.\n\nThe timing gate evaluates file-click-to-text-completion, first exact search, changed query, last-match navigation and maximum viewer timer-service gap. Missing, non-finite or negative samples fail every run; `SAMBEE_E2E_BUDGETS=1` also fails over-budget samples. Omit that flag for functional-only runs, which still attach the budget result. Forced-GC and tracing runs are marked diagnostic and can't enforce timing acceptance. Run `npm run test -- src/utils/__tests__/viewerPerformanceBudgets.test.ts` from `frontend/` for the evaluator's boundary and error tests. These browser-independent checks also run in the normal Vitest CI suite, without repeating them for each browser project. To validate a recorded report, the existing Playwright entry point remains available: `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_REPORT=/tmp/report.json SAMBEE_E2E_SLICE=publication npm run test:e2e -- viewer-performance-budgets.spec.ts --workers=1`.\n\nSearch/query/navigation probes start in browser event handlers, observe the expected count and active highlight in the existing small search controls, and finish after two frames. They avoid page-wide text queries and Playwright round-trip timing, but aren't hardware input-to-visible-paint measurements. The existing active-search fixture deliberately holds syntax preparation; text-load completion doesn't include syntax. Fresh/cached grammar isolation, first usable text/highlight completion, source editing, large prose/tables, resource acceptance and native interaction still require their own evidence. A passing timing subset isn't full rollout acceptance.\n\nThe browser checks compare exact rendered text, native Select All, selected code text and accessibility-tree output. They also exercise keyboard focus, safe links/HTML, GFM tables/tasks, shared Find navigation, theme-variable updates without text-node replacement, native copy events and Chromium PDF generation. These don't establish OS clipboard payloads, browser-native Find reveal, assistive-technology behavior or visual full-document print/PDF correctness. Those remain manual gates.\n\nThe separate native-constraint slice checks representative multiline, long-line and nested Markdown at widths 1543/390 in Chromium/Firefox. It compares cross-block selected text with a trusted keyboard copy/paste payload, exercises keyboard focus and native `window.find` selection/reveal, and attaches real Chromium PDFs. The native text-find API isn't the browser Find toolbar, and a narrow desktop viewport isn't a physical phone. From `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-native-constraints.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production native Markdown constraints' --workers=1 --reporter=json\n```\n\nFrom the repository root, check the attached PDF text with the existing backend environment:\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-native-constraints.json\n```\n\nThe checker rejects missing/duplicate PDF cases, unsuccessful browser results and missing rendered-document lines. Heading IDs use a safe prefix and standard duplicate/Unicode slugging in the existing HAST pipeline; matching fragments are rewritten consistently. Native and printing matrices have independent checks. Chromium's `window.find` reveal is diagnostic-only because it can select without scrolling even outside Sambee; exact selection remains required in both engines, and Firefox reveal remains enforced. Don't add application scrolling to manufacture a native Find pass.\n\nThe Markdown preview's Print icon calls the native browser print dialog; Save as PDF is a destination in that dialog, not a second renderer or server-side conversion. Print isn't offered in edit mode or enabled while loading has failed or is incomplete. Print-only styles hide controls/background UI, release fullscreen/scroll constraints, wrap code/table cells, retain images and use black text on white regardless of the screen theme. Native `beforeprint`/`afterprint` handlers preserve focus, selection and nested scroll, with pending callbacks removed on disposal. The fullscreen paper sizes against its fixed container rather than dynamic viewport units that can retain print-page dimensions.\n\nRun the independent print matrix from `frontend/`, then inspect the PDF attachments from the repository root:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-markdown-printing.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production Markdown printing' --workers=1 --reporter=json\n```\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-markdown-printing.json --printing\n```\n\nThe 24-case matrix covers three fixtures, both themes, both widths and both engines. It verifies action invocation, print CSS, wrapping/widths and actual Chromium PDF state restoration. The PDF gate requires all 12 Chromium outputs to contain every rendered non-whitespace text line and an embedded image. Clear any forced screen-media override before PDF generation; otherwise Playwright prints screen CSS. First/last-page raster inspection supplements text checks. Firefox CSS checks aren't actual Firefox PDF evidence. Actual Firefox PDF and desktop/physical printing were separately confirmed complete by the user on 2026-10-24; no detailed browser/printer support matrix is inferred. Browser destination, paper, margin and header/footer settings remain user-controlled.\n\nKeep performance changes local to measured costs in the current path. Distinguish first visible syntax from completion of all block preparation, and include serialization and parent updates when measuring typing or atomic replace-all. Configuration-only theme and grammar updates must not request caret reveal or replace the document, selection or editor. Don't add streaming, scheduling abstractions or new edit protocols without evidence that the existing path misses its target.\n\nThe existing viewer harness also has a `production source responsiveness` slice for the 54,000-unit dense and 6,000-match long-line source fixtures. It verifies bounded worker delivery, one atomic replacement, undo/redo, exact saved file bytes and worker termination. Save assertions decode the complete multipart body received by the isolated test HTTP proxy; Playwright's request snapshot can omit uploaded file bytes. All traffic uses fixtures, never stored demo edits.\n\nLarge Replace All operations may temporarily block the editor while CodeMirror applies their atomic change set. This latency is an accepted limitation under D5, not permission to truncate output, split history or replace the entire document instead of preserving logical changes. Text and Markdown editors share an editor-owned indeterminate replacement indicator. Worker preparation shows it only after 200 ms; completion before that threshold cancels it without a flash. Ordinary literal replacements stay synchronous and aren't given an artificial delay.\n\nBefore a known-heavy apply, the indicator is shown and given two animation-frame callbacks so the browser has a paint opportunity before the native dispatch. The conservative workload gate requires at least 1,000 replacements and at least 50,000 UTF-16 units in the source or inserted payload. Literal commands inspect at most 1,000 matches for this estimate; worker commands use the completed change plan. This isn't a duration prediction: some fast workloads may be classified as heavy, and unexpectedly slow synchronous work cannot reveal a delayed indicator while blocking the main thread. Feedback already visible during preparation also receives a paint opportunity before application. There's no minimum visible duration or delayed completion, and the spinner doesn't promise continued animation or input responsiveness during synchronous apply.\n\nThe same command boundary covers toolbar and keyboard Replace All. Pending replacements reject duplicate invocations. Any introduced yield revalidates the exact document, query, selection and writability; editing or switching state cancels obsolete work rather than applying stale replacements. Failure, timeout, cancellation and editor disposal release the indicator, animation, timers and listeners. Hidden documents don't wait indefinitely for throttled animation frames. The status uses the editor theme, exposes accessible busy/status semantics and respects reduced motion; physical assistive-technology behavior remains a separate manual check.\n\nThe `production replacement feedback` slice checks quick no-flash behavior and captures visible feedback with the original source still present, then releases held frames and verifies atomic undo/redo, exact multipart Save and editor cleanup in both engines at widths 1543/390. Its held-frame evidence is functional, not timing acceptance.\n\nSource edits retain one bounded User Timing entry per stage: `sambee:source-editor:serialize`, `sambee:source-editor:publish`, `sambee:source-editor:normalize` and `sambee:source-editor:parent-update`. The enclosing publication includes normalization and the synchronous parent callback. These overlapping stages mustn't be added together. Entries contain lengths/revisions, not document contents. `sambee:source-search:commit` brackets the native atomic dispatch, including its synchronous listeners; deferred React work isn't isolated CPU time inside that measure. The separate click-to-completion probe waits for the parent dirty-state render and two subsequent frames. That boundary is a scheduling proxy, not hardware paint.\n\nFrom `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-responsiveness.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nEach sample attaches source-private measurements and explicit 50 ms atomic-dispatch, enclosing serialization/publication and maximum-timer-gap checks. Missing or invalid evidence fails even without `SAMBEE_E2E_BUDGETS`; that flag additionally enforces the original limits. Retain the failed native atomic-application timing results as diagnostic evidence of the D5 accepted limitation, not as passing samples or a reason to repeat performance-only matrices. Unrelated source timing, worker correctness and resource gates remain required. Transfer counts aren't retained/peak memory evidence, and these fixtures don't establish sustained typing, large-table normalization, dense output expansion or scrolling acceptance.\n\nThe separate `production source typing` slice types 82 characters at a requested 10 ms inter-key delay into each 54,000-unit fixture, without per-key polling. It records trusted browser keydown-to-first/two-frame samples, timer gaps, all four edit stages and optional whole-renderer Long Tasks entries, then verifies exact saved source plus the payload. The `source-typing` attachment enforces two-frame p95 strictly below 50 ms and stage/gap maxima at most 50 ms. All 24 engine/width/repeat trials pass; the worst per-trial p95 is 35 ms. This is a scheduling proxy, not physical input-to-painted-pixel acceptance. Unsupported Long Tasks capability stays unmeasured, and observed tasks wouldn't establish application-owned CPU attribution.\n\nThe `production prose table responsiveness` slice mounts the approved 4,000 formatted paragraphs or 2,400 two-column table rows. It checks every rendered paragraph/cell exactly, preserves native block whitespace, root/text-node identity and full rendered text through 60 programmatic scroll steps, and verifies cross-block native selection and close cleanup. Load timing runs from the browser's file-open click through two frames after all expected blocks mount. The `prose-table-responsiveness` attachment separates load budgets, the earlier two-viewport geometry milestone and diagnostic rAF scroll intervals, including the frame following the final scroll assignment. The final 24 trials complete within 1,110 ms, with the first viewport available within 761 ms. Nineteen trials exceed the unchanged 50 ms timer-gap limit, with a worst gap of 128 ms. These recorded loading pauses are accepted under D6, not passing timing samples or isolated CPU attribution. Headless rAF intervals don't establish physical refresh rate, wheel/touch, compositor or painted-frame acceptance. These fixtures have no fenced syntax and don't measure syntax readiness or large-table source normalization.\n\nThe separate `production progressive Markdown loading cancellation` slice holds frame callbacks after two viewport heights exist. It requires visible feedback, disabled document controls, loading-only print output and a working Close action, then releases stale callbacks and verifies complete reopening. It runs in Chromium and Firefox at widths 1543/390. Its paused screenshots and functional passes aren't timing evidence. The existing large-code publication, native interaction and print matrices remain independent regression checks; their completion and acceptance boundaries are recorded below.\n\nRun these slices separately from forced GC and CPU profiling:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-typing.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source typing' --workers=1 --repeat-each=3 --reporter=json\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-prose-table-responsiveness-final.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production prose table responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nFor separate Chromium load attribution, select the same prose/table slice with `SAMBEE_E2E_TRACE=1` and no budget enforcement or forced GC. The `viewer-load-cpu-profile` and `viewer-load-timeline` attachments span file open through completed mounting; nonempty CPU samples and both `sambee:viewer-load:start`/`sambee:viewer-load:complete` timeline markers are required. Budget status is diagnostic, never acceptance. Two desktop captures show one preview build, with a 126.05 ms prose render callback and a 53.69 ms table callback before native style/layout. The prose clone, transforms and HAST-to-layout-effect stages take 38.3, 37.5 and 44.5 ms; these overlap the encompassing callback and mustn't be added to it. Prose native style/layout takes a further 21.14/38.13 ms. Keep cached-tree isolation and native document semantics; neither deleting the clone nor an unapproved publication/renderer change is justified by this evidence. Firefox/mobile CPU attribution remains unverified.\n\nChromium CPU sample deltas can be negative. Reconstruct cumulative sample timestamps, sort them, then clip nonoverlapping intervals to the load markers. Summing only positive deltas inflates CPU weights. Use the marker's renderer PID/thread for main-thread timeline attribution; worker processing and unclassified native samples aren't automatically application-owned blocking CPU.\n\nRepeated source-regex Next/Previous requests are queued in order while navigation is pending. The active navigation worker reuses its transferred document for that burst, applying each native CodeMirror command from the preceding result's selection with the current position's whole-word rules. It terminates when the queue drains; no idle worker is retained. Document/query changes, external selection changes, replacement commands, failures and disposal cancel obsolete queued navigation. Unit tests compare reused-worker navigation with native commands, including mixed directions, wraparound, overlapping matches and zero-length expressions.\n\nThe independent `production source regex parity` slice compares counts and exact saved output with the installed CodeMirror commands for zero-length lookahead, case-sensitive and whole-word matching. A replacement exceeding two source-transfer chunks verifies continuation assembly without truncation. `production source regex lifecycle` injects worker-construction, error/decode-event and startup-timeout failures, requires actionable feedback and a successful retry, and preserves continued editing and exact Save bytes. A partial-delivery case lets one replacement chunk arrive before cancellation, then replays stale change/completion messages; no partial replacement may be committed. These are host-side fault injections, not actual browser-process crash or structured-clone failure evidence. Run both functional slices with:\n\n```sh\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production source regex (parity|lifecycle)' --workers=1\n```\n\nFor optional source renderer footprint diagnostics, use `SAMBEE_E2E_MEMORY=1` without timing enforcement, select `production source responsiveness`, and run the Chromium-only `npm run test:e2e`. The `source-renderer-memory` attachment records CDP renderer heap after explicit GC at pre-open, counted-results, post-replacement and post-close boundaries. Its historical 64 MiB assertion isn't a release criterion under D11. These are whole-viewer post-GC observations, not isolated result-array bytes, peak/worker/native memory or proof of leak-free cleanup. Staged/peak-memory limits and a fixed close/reopen cycle protocol aren't required. The source budget status is diagnostic in memory mode.\n\nFor a separate Chromium CPU diagnostic, use `SAMBEE_E2E_TRACE=1` without `SAMBEE_E2E_BUDGETS=1`, restrict the grep to `production source responsiveness long-line at 1543px`, and run `npm run test:e2e`. The `source-dispatch-cpu-profile` attachment contains the CDP CPU profile; its source budget status is diagnostic, never an acceptance pass. The source slice rejects combined profiling/GC and either diagnostic mode combined with timing enforcement.\n\nFor separate controlled-memory trials, add `SAMBEE_E2E_MEMORY=1` and restrict the existing matrix to the many-block fixture and Chromium. Release harness-held node references before post-GC sampling. Renderer heap excludes worker heaps and aggregate/native memory; a single close isn't repeated-close leak acceptance. Keep forced GC separate from responsiveness timing.\n\nFor diagnostic scheduling traces, add `SAMBEE_E2E_TRACE=1` to a single-fixture Chromium run. The `viewer-scheduling-trace` attachment contains a CDP timeline and V8 CPU profile. Align `sambee:viewer-trace:start` with browser timestamps; join CPU chunks by renderer PID and profile ID and count samples once. Firefox native profiling must use content-process User Timing markers rather than parent-only samples. Profiling adds overhead and isn't acceptance timing.\n\nTo isolate native table input from application work, run the existing proof from `frontend/`:\n\n```sh\nSAMBEE_NATIVE_TABLE_REPORT=/tmp/sambee-native-table node scripts/source-search-containment-proof.mjs --native-table\n```\n\nThis uses public CodeMirror/Lezer and `markdownTables` APIs at the approved demo URL, with an isolated HTML response and default package styling. It edits the middle cell of the fixed 2,400-row table at 1543x900 without React, application CSS, normalization, Save or workers. It requires exact complete native source, atomic full-table replacement spans, native undo/redo and disposal. Native table source uses `\u003cbr\u003e`; application canonicalization to `\u003cbr /\u003e` isn't part of this proof. Root state materialization and view-update intervals are reported separately; input-to-root includes scheduling and deferred publication, not just model CPU. The unminified desktop diagnostic isn't a production acceptance trial or a replacement for mobile, composition and lifecycle checks.\n\nThe optional report prefix writes per-engine JSON and the exact diagnostic bundle. For separate profiling, add `SAMBEE_E2E_TRACE=1` and configure `MOZ_PROFILER_STARTUP=1`, `MOZ_PROFILER_STARTUP_FILTERS=GeckoMain`, `MOZ_PROFILER_STARTUP_FEATURES=js,stackwalk,leaf` and `MOZ_PROFILER_SHUTDOWN` with an absolute output path. Chromium records input-only CPU samples; clip Firefox content-process samples between `sambee:native-table:input-start` and `sambee:native-table:input-end`, excluding construction and history checks. Profiling requires a report prefix and Firefox startup configuration; product-budget enforcement and controlled-GC modes are rejected. Inclusive model, parsing and native reflow samples overlap and mustn't be summed. Unclassified Chromium native samples aren't automatically package JavaScript CPU. Slow native input doesn't by itself establish slow atomic state application or justify private package patches, changed history, wrapping or selection semantics.\n\nCount assertions remain scoped to the existing search controls to avoid page-wide Playwright text caches inside measurement windows. Results are labelled `scoped-controls-v2`; older input figures aren't directly comparable. Handler-to-frame samples and synthetic event age don't establish hardware input-to-visible-paint latency. Removing the alternate renderer doesn't close any performance, memory or manual interaction gate.\n\n### Shared Highlighting Acceptance And Limitations\n\nThe shared-highlighting implementation was approved by the user for merge and rollout on 2026-10-24. Approval doesn't turn failed measurements into passes or establish support for untested devices. Keep original targets, raw verdicts and these scoped acceptance decisions together:\n\n| Decision | Accepted scope | Boundaries |\n|---|---|---|\n| D5 | Noticeable large atomic Replace All latency with visible busy feedback. | Preserve complete output, logical change mapping, one native transaction and undo/redo. Unrelated source-search or typing pauses aren't accepted by this decision. |\n| D6 | The recorded progressive prose/table preview-loading pauses: 19/24 trials above 50 ms, worst 128 ms; all complete within 1,110 ms. | These remain failed gap samples. Longer future delays and other workloads aren't covered. Asynchronous preview preparation remains declined. |\n| D8 | Responsiveness limitations of the existing Markdown table editor. | Table-component timing is diagnostic and non-blocking; exact input, Save, composition, history and cleanup remain required. |\n| D9 | Ten recorded Firefox many-block syntax-color samples at 1,511-1,579 ms against the 1,500 ms target. | All 120 cold/warm samples were collected; 110 meet that target. Full syntax preparation stays within 3,000 ms. No broader delay exception is implied. |\n| D10 | Four recorded Firefox desktop code-display gaps at 51-59 ms against 50 ms. | Preserve the raw failures. Additional delayed-image/font/resize and scroll-anchor test coverage was removed, not passed. Correct content, selection and scrolling remain required. |\n| D11 | Leak investigation and fixes for demonstrated unwanted retention, rather than quantitative memory acceptance. | Staged/peak-memory limits and fixed-cycle shutdown checks were removed, not passed. No exhaustive leak-free claim is made. |\n| D12 | Removal of real-phone and physical keyboard/IME acceptance, including phone print UI and hardware-response measurements. | This isn't verified device support. Automated keyboard/composition, exact editing/Save/recovery and desktop native/print correctness remain required. |\n\nBrowser-menu Find/reveal, OS clipboard, assistive-technology and physical-scrolling checks were confirmed complete by the user on 2026-10-23. Remaining Firefox PDF and desktop/physical printing checks were confirmed complete on 2026-10-24. These are user confirmations, not new automated measurements or a detailed device, browser, AT or printer support matrix. Don't reopen completed checks or rerun accepted timing failures solely to close a checklist; retest affected behavior after a relevant change or demonstrated regression.\n\nThe final editing checks cover theme changes followed by editing exit and Close, late worker results, distinct documents, captured-revision Save with newer dirty edits, failed writes and recovery/snapshot failures. Source-regex terminal cleanup detaches worker handlers, releases terminated workers and clears obsolete replacement buffers, while retaining buffers needed for a pending atomic apply. Ownership review and lifecycle assertions establish the investigated cleanup, not a heap-retention proof for every browser object.\n\nUse `PLAYWRIGHT_JSON_OUTPUT_FILE`, not `PLAYWRIGHT_JSON_OUTPUT_NAME`, for an explicit report path with the JSON reporter. Preserve complete identities, both engines, widths 1543/390, original workloads and three trials per timing identity. Recorded-report evaluation must retain failed samples and reject missing, duplicate, invalid, skipped or retried identities. Functional-only runs and tracing/GC diagnostics don't establish timing passes. Retain local reports before temporary-file cleanup; overlapping runs aren't additive test totals.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. Dedicated formats need a coordinated backend/frontend contract update. Languages already present in the shared CodeMirror catalogue need no separate extension registration for text opening; extra frontend entries are only needed for MIME or presentation metadata.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/fileLanguages.ts` | reuse shared language filename matching; maintain additional plain-text extensions here rather than duplicating language extensions |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare dedicated viewers and optional MIME/presentation metadata; text-viewer assignments are derived automatically |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or the unified `TextEditor`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npm run typecheck\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.8": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.9": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "1.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "2.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must agree on image formats, conversion requirements, and MIME types used for dedicated viewers\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/fileLanguages.ts` | shared CodeMirror language catalogue, filename matching, and additional plain-text extensions used by highlighting and default text opening |\n| `frontend/src/utils/FileTypeRegistry.ts` | dedicated viewer mappings and MIME/presentation metadata; derives text-editor support from shared filename recognition |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nDedicated formats such as images require backend and frontend agreement. Text-file recognition instead uses `fileLanguages.ts`: both highlighting and default text opening consume the same CodeMirror catalogue. Language metadata doesn't load a grammar or import the highlighting core into the file browser.\n\nExplicit image, PDF, and Markdown viewers take precedence over extension-based text recognition. A recognized, non-generic MIME type with a viewer mapping takes precedence over the filename; empty MIME types, `application/octet-stream`, and `text/plain` fall back to filename recognition. Saved viewer preferences override the default selection. Unknown files still use the viewer picker unless a MIME mapping or saved preference selects a viewer.\n\nAll file viewers and editors use `useViewerDocumentTitle` to set the browser tab title to the active filename, including its extension. Image navigation updates the title to the active image. Native print events temporarily remove the final extension so browsers can suggest a clean PDF filename. The Markdown Print action uses the hook's print callback to prepare the title before opening the dialog and restore it after a print failure. Successful calls retain the short title until `afterprint`; `window.print()` can return before the print dialog closes. Closing the workspace restores the previous title unless another owner has changed it.\n\n## Unified Text Editor\n\n`TextEditor.tsx` owns the text destination and reuses `TextCodeEditor` for writable and read-only content. There isn't a separate text-viewer component or an Edit action. The public `viewer=text` identifier, viewer preferences, settings, and recovery-draft keys remain compatible. Text routes accept absent, `view`, and `edit` modes as the same destination; canonical URLs omit `mode` without adding a history entry or dropping fragments. Markdown still uses its existing preview/edit route modes.\n\nOpening an eligible text file automatically calls `beginViewerTextEdit`. The editor stays read-only until acquisition succeeds and a fresh content read establishes the baseline. Archive members, read-only connections, and oversized files don't acquire sessions. Storage boundaries distinguish contention, denied permissions, unsupported editing, and temporary unavailability. SMB's acquisition request opts into a non-mutating per-file write probe; Companion also checks an existing file with read/write open and no creation or truncation.\n\nAcquisition feedback appears after 200 ms as a small spinner beside the filename, in a fixed-size toolbar slot. Fast acquisitions show no progress message, and slower ones don't move the document. Completion, navigation, and unmount cancel pending feedback without delaying readiness. Access failures remain immediate; related error details and the read-only reason share one notice with Retry where supported.\n\nAcquisition uses an activation generation to release obsolete results, and a pending release completes before another acquisition starts. Confirmed lock loss or revoked access freezes mutations and retains the draft; a transient heartbeat failure shows a warning. Retry is explicit, not an acquisition loop. A fresh baseline that differs from a retained draft's original baseline requires a conflict decision before editing resumes. Choosing the draft doesn't save it.\n\nText and Markdown saves pass `reacquireExpiredLock: false`; they must not silently reacquire an expired lock and overwrite a changed file. Save acknowledges only the captured revision, preserving newer edits as dirty. The routed leave guard protects dirty navigation and pending operations. Text Close goes directly to the file list after release, and Discard commits a clean state before navigation so the guard doesn't prompt twice.\n\nSave from a valid active session can recreate a file deleted at the original path. It can also overwrite changes made at that path; it does not detect replacement files. Failed writes retain the draft. The dynamic host mounts one viewer, not a hidden candidate alongside the current document. Each viewer owns its load and error state; the image gallery reuses only its own local cache.\n\nRead-only disables typing, Save, and Replace, not Find, selection, copying, wrapping, download, or sharing. Recovery is resolved before automatic activation. Keep regressions for late acquisition, Strict Mode, read-only and conflict states, history navigation, and Markdown's separate lifecycle when changing this shared path.\n\n## Shared Viewer Notifications\n\n`ViewerNotifications.tsx` reuses the application notification host, shared edit-lock message mapping, and delayed acquisition indicator for text and Markdown. There is no viewer-corner or pane-local toast host in the file browser. Markdown retains its preview/edit lifecycle, but uses the same lock/read-only notification, filename badge, explicit Retry action, and retained-draft conflict decision. Lock release completes before another acquisition starts; obsolete acquisition results are released without publishing errors.\n\nEach viewer supplies active notices with stable IDs, severity, and operation occurrence numbers. One host displays one bottom-center toast across both panes and all viewer and page operations, prioritizing errors over warnings and information. Next notification exposes another pending condition. Dismissed heartbeat and draft-storage conditions stay dismissed until resolution or a changed condition. A new operation failure can notify again even when its message is unchanged. Resolved notices leave the active set, and source identities isolate dismissal state between files. Moving the host into a modal does not reset dismissal state.\n\nAll Text and Markdown editor toasts expire after 15 seconds, including informational lock notices, edit and save errors, print errors, heartbeat warnings, and draft-storage warnings. Hover or keyboard focus pauses expiry. Expiry hides only the notification; it does not clear the error, release a lock, discard a draft, or change the edit session. There is no additional inline warning after expiry. Existing editor controls and unsaved-change safeguards remain available. Toasts don't take focus or change document geometry. Recovery and unsaved-changes dialogs retain their own failure notices and suppress viewer toasts while open. Document-load failures, file-size limits, search validation, and editor-load/crash recovery remain in context rather than moving into the toast queue.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nPhysical streams read their first chunk before sending response headers. An initial read failure can therefore return a safe structured error. A later read failure terminates the stream and closes the backend; it cannot replace an already committed HTTP response with JSON. PDF derivative preparation reads its source before returning bytes, so a source failure during that buffered read can still use the structured error boundary. Native-download intent redemption uses the same prepared-stream boundary.\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### PDF Loading And Password Cancellation\n\nThe PDF viewer keeps the document hidden and its controls disabled until the active page's canvas has rendered. The loading indicator and text appear only after 500 ms. A fast load shows neither. Each new document, retry, or compatibility attempt starts a new feedback delay. Readiness does not wait for text extraction or a minimum indicator display time.\n\nEscape, Cancel, and the mobile back action in the password dialog cancel the current PDF load. Cancellation clears the password, unmounts the document to destroy its PDF.js loading task, releases its blob URL, and shows a notice with Retry. It does not submit an empty or null password, and it does not request compatibility processing. Downloading the original remains available through the viewer's existing download action. Only an explicit retry can start a new password request after cancellation.\n\nPassword callbacks belong to one load session. The viewer ignores callbacks from canceled or replaced sessions. An incorrect password can request another attempt within the same active session.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation. Its text-layer markers use `frontend/src/utils/domTextSearch.ts`.\n- Rendered Markdown uses a preview-owned session in `frontend/src/utils/viewportDomTextSearch.ts`. It reuses the DOM index and matcher from `domTextSearch.ts`, preserving rendered-text boundaries, cross-inline matches and exact code whitespace.\n- Markdown edit mode doesn't reuse the rendered-view DOM search implementation. It bridges the same outer toolbar UI into the editor-specific search state and commands instead.\n\nThe Markdown preview separates logical matches from their presentation. It retains exact match positions and text-node mappings, but paints at most 1,000 viewport search ranges plus one active-match range through CSS Highlights. Search doesn't insert markers, split text nodes or replace preview content. Navigation resolves the destination directly from the index and scrolls the content viewport, including for off-screen matches.\n\nEach preview generation owns its search session. Query changes reuse the unchanged DOM index; text replacement or character-data changes invalidate it. Syntax painting and theme-variable changes don't invalidate it. Scroll, resize, image loading and font readiness refresh presentation without matching the document again. Disposing the preview removes its highlights, style, observers, listeners, cached text and pending animation frame. PDF search remains independent.\n\nDOM capture collects text chunks and joins them once, preserving numeric offsets and block separators without repeatedly flattening the growing source. Syntax publication separately caps its viewport ranges and clips horizontally overflowing unwrapped code to visible columns. Both search and syntax skip vertical character-range lookup when the owning text box is wholly inside the viewport; partially clipped boxes retain exact boundary lookup. Horizontal clipping is independent of that fast path: the left lookup can stop at the first character, and the right lookup reuses the exact left boundary as its lower bound. Disjoint horizontal clips produce no ranges. These optimizations don't estimate character widths or cache geometry. Nested code-block scrolling refreshes syntax and search ranges without changing the source or search index.\n\nSearch highlight colors inherit the preview's scoped theme variables. Browsers without CSS Highlights retain counts and indexed navigation without visual search highlighting; the viewer logs that limitation rather than falling back to whole-document marker insertion. Browser support and whole-viewer performance acceptance remain separate rollout gates. Cached indexing doesn't guarantee responsive capture or rendering for arbitrarily large documents.\n\nUse the existing production-viewer check in `frontend/e2e/markdown-viewer.spec.ts` to attribute performance within the ReactMarkdown path. Its User Timing entries separate preview-search lookup, geometry, scrolling and publication from syntax mapping, geometry, range construction and publication. Geometry reads may force layout; registry calls can include native browser work, but don't necessarily include deferred painting. Worker round trips include transfer and acknowledgements, not just parsing. Source-response, DOM-commit-observer and frame milestones narrow initial-load costs without claiming isolated React CPU or hardware input-to-visible-paint latency. Functional passes don't establish the responsiveness budgets.\n\nInitial-load Markdown normalization uses the shared helper in `frontend/src/utils/markdownCodePreparation.ts`. Documents of at most 4,096 UTF-16 units run the existing canonical normalizer directly, avoiding worker startup and transport for small notes. This bounded path returns the same canonical text and prepared MDAST; it doesn't skip normalization or change rendering. The size limit lives in the shared preparation protocol. Larger documents each own a preparation worker and transfer source, canonical text and an equivalent canonical MDAST in acknowledged, bounded chunks. Tree batches contain at most 512 records and 16,384 string UTF-16 units; individual field pieces are at most 2,048 units. Numeric/flag/position metadata is validated separately, and large text and table alignment fields use the chunk channel instead of content limits. Host acknowledgements yield between tree batches. Success, cancellation, decode failure and timeout terminate the worker; aborted loads can't publish content. Worker failures use the existing load-error path without a synchronous retry, and local preparation failures aren't reported as server overload. The pre-app capability gate requires a callable Web Worker API and otherwise shows the existing unsupported-browser screen without importing the app. The helper retains defensive synchronous normalization with a diagnostic for larger documents when workers are unavailable, but Worker-less app operation isn't supported. API presence doesn't guarantee successful worker construction or execution; existing startup, timeout, crash and decode-error handling remains necessary. The shared protocol is DOM-free. Vite's shared resolver aliases the character decoder to its non-DOM implementation before dependency optimization, so development and production workers use the same implementation. A worker-build-only resolver isn't sufficient for development's prebundled dependencies.\n\nReactMarkdown remains the only application whole-document renderer in every build mode. Its parser hook reuses a defensive clone of the prepared tree only when the tree matches the preview generation's exact source. All normal remark transforms, GFM, table-cell break handling, safe URL/raw HTML behavior and React rendering remain in that path. Cloning prevents those transforms from mutating the retained canonical tree. A successful Save that changes the source releases the superseded tree; edited content without a matching tree uses the normal parser.\n\nRendered Markdown sources of at least 50,000 UTF-16 units use `ProgressiveMarkdown` to append the existing pipeline's fully transformed output. Document-wide references, headings and GFM are resolved once before staging. Chunks aren't parsed as independent Markdown documents. Ordinary sources keep their immediate rendering path. Staged batches use the same ReactMarkdown rendering and safe-link/raw-HTML handling, with at most 1,024 structural nodes or 8,192 text units. Oversized tables, containers and code blocks are subdivided internally, preserving one native table or code block rather than splitting it into separate documents. Already-published nodes aren't replaced by later appends.\n\nThe viewer targets two viewport heights for the initial fill, then yields. Later frames use the 4 ms elapsed-work target without a height limit or repeated per-batch geometry reads. Each frame commits at most four batches, checking elapsed time after every commit to bound work accumulated before native layout. Neither the fill target nor these limits guarantee a maximum task duration: whole-document cloning/transforms, a single commit and native layout remain synchronous. Visible pages use animation frames; hidden pages use timers so completion doesn't wait indefinitely for a frame. Source or rendering-configuration changes and disposal cancel the old publication owner; a restarted generation resets document readiness. A 200 ms delayed, accessible loading indicator disappears immediately on completion and respects reduced motion.\n\nReading published text and closing the viewer remain available during progressive loading. Document search/counts, editing, heading-link navigation and toolbar printing wait for complete publication; syntax painting and DOM search indexing also wait. Browser-menu printing while loading shows a loading notice instead of partial document content. Once complete, normal native selection, search, links and print behavior apply. These controls prevent partial results from being presented as complete; they don't promise that synchronous preparation can never block input.\n\nMarkdown editing reuses the preparation worker for full-document canonical normalization when the editor source contains `\u003cbr`. The existing no-`\u003cbr` typing path still publishes immediately without normalization. If both the original baseline and edited document contain possible table syntax, a background preservation-only job compares their tables without changing that typing normalization policy. Identical sources or documents without a pipe character need no table comparison. Each editor owns at most one active job and one replaceable latest request. Only the current source, baseline, policy and generation can satisfy a prepared snapshot; obsolete success, failure and diagnostic messages are ignored. Worker acknowledgements never replace the native CodeMirror document, recreate table-cell editors or change transaction history. Pending table/IME publication and worker preparation keep the viewer dirty independently of canonical draft publication. External source changes and unmount dispose the old owner and its workers; a baseline change invalidates unmatched prepared bytes.\n\nToolbar Save takes focus before its click handler captures selection. The rich editor therefore remembers the active nested table cell on native focus entry and departure, and refreshes that snapshot when selection is explicitly preserved inside the editor. Stay-edit Save restores the same connected cell within the current root instead of focusing the root and triggering native table-widget reconstruction. If the cell document changed while Save was pending, restoration keeps its newer native selection rather than replaying old offsets. Returning to root-text editing, replacing the external document and unmounting clear the remembered cell; disconnected or replaced cells use the existing root-selection fallback. This doesn't change native transactions, history grouping or composition handling. Production checks require retained cell identity/focus after Save, continued typing, and native undo/redo; these functional checks don't establish responsiveness acceptance.\n\nAsync snapshot capture flushes table/IME publication and worker preparation within the existing transition deadline. It requires full-document normalization even after the typing fast path, so Save retains list, escape and table canonicalization. The same worker performs the unchanged AST-aware table comparison against the exact original baseline, preserving original source for semantically unchanged tables. Source and baseline transfer sequentially in acknowledged chunks of at most 16,384 UTF-16 units, with generation and sequence validation; result chunks retain the same bound. Edit preparation doesn't request a preview tree, whose offsets would no longer match preserved source. Save consumes immutable, complete source-preserving snapshot bytes; repeated serialization returns the captured string without parsing. A successful write acknowledges only its snapshot: newer pending edits stay dirty, and an unavailable newer snapshot doesn't turn the completed write into a failure. Worker failure preserves editing and dirty content; a subsequent explicit async snapshot request can retry, but failures never trigger a synchronous parsing fallback or an automatic retry loop.\n\nSynchronous snapshot capture and canonical getters reject pending or failed worker preparation, including an unmatched source-preservation baseline, rather than returning an older revision as current. Recovery retains its synchronous pagehide/pre-sign-in attempts, debounce and limits; failed capture logs the failure and shows the existing recovery warning. It doesn't mark content saved. Native text sharing is unavailable while publication is pending and reads a complete snapshot when ready. Worker-side normalization and source preservation don't establish whole-viewer timing or resource acceptance; native table editing, layout and preview reconstruction remain separately measured costs.\n\nThe bounded `sambee:edit-preparation:*` entries separate queue wait, worker startup/first acknowledgement, source and baseline transfers, run-to-first-result, result delivery, total transport/job time and complete async snapshot flush. Numeric metadata records generation, source/baseline lengths, policy, chunk counts and whether a completed job is current or obsolete; it contains no source text. Transport completion also reports worker normalization and source-preservation durations separately. Host intervals include event-loop scheduling and acknowledgement delays, so startup isn't isolated worker boot time and transfer isn't pure wire time. Worker durations aren't main-thread CPU, and nested intervals mustn't be added to their enclosing job or snapshot flush. Each stage retains only its latest entry; the existing test observer collects individual samples. Use these measurements to distinguish Save wait from the native table/focus work that can follow write acknowledgement, not to infer a faster Save or passing keyboard/paint budgets from worker offload alone.\n\nThe bounded `sambee:preview-preparation:*` entries separate asynchronous decode elapsed time, load normalization, tree cloning, code-block collection and ReactMarkdown transforms. For worker-backed loads, `load-normalization-elapsed` includes worker startup, transfer, work, host tree assembly, acknowledgements and scheduling, not main-thread CPU time. For small notes, it measures direct canonical normalization and prepared-tree creation. `render-prepared-tree` measures the defensive clone; `render-parse` measures normal parsing when no matching tree is available. The initial-load production matrix requires the clone stage and rejects synchronous `render-parse` and standalone `collection-parse` stages. Live syntax request collection walks the renderer's existing tree; it doesn't parse source again or change markup. The `collection-walk` interval is included in `render-transform`, not additional time to sum. Each generation publishes its ordered requests after DOM commit, before the passive syntax preparation effect, which snapshots them and retains cancellation and stale-generation guards.\n\nThe HAST-ready-to-layout-effect interval includes element construction, reconciliation, commit and scheduling, not just React CPU or paint. Entries contain no source text; each stage retains its latest measurement while the browser test observer collects individual samples. Normalization reuses its parsed tree when canonicalization leaves the source unchanged and reparses in the same preparation path when edits change source offsets. Tree reuse doesn't close responsiveness, retained-memory, syntax-completion or native interaction acceptance.\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Single-Renderer Acceptance\n\nThe retained whole-document viewer integration and its special build-mode selection have been removed. Don't reconnect the historical publisher or add a second renderer to finish shared highlighting. Reuse ReactMarkdown, its parsed-tree code collection, the existing workers and viewport CSS highlights. Standalone renderer proofs are historical research, not application acceptance or a delivery dependency.\n\nRun `npm run build`, then `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production syntax publication' --workers=1 --repeat-each=3` from `frontend/`. The existing matrix uses the approved demo connection and unchanged dense, near-safeguard, host-envelope, many-block and long-line fixtures in Chromium and Firefox at desktop and narrow widths. Add `PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-reactmarkdown-baseline.json` and `--reporter=json` to retain structured reports without npm's console preamble. Each fixture attaches `viewer-timing-budgets.json`, with observed values, numeric targets, pass/fail results and criteria that remain unmeasured.\n\nThe timing gate evaluates file-click-to-text-completion, first exact search, changed query, last-match navigation and maximum viewer timer-service gap. Missing, non-finite or negative samples fail every run; `SAMBEE_E2E_BUDGETS=1` also fails over-budget samples. Omit that flag for functional-only runs, which still attach the budget result. Forced-GC and tracing runs are marked diagnostic and can't enforce timing acceptance. Run `npm run test -- src/utils/__tests__/viewerPerformanceBudgets.test.ts` from `frontend/` for the evaluator's boundary and error tests. These browser-independent checks also run in the normal Vitest CI suite, without repeating them for each browser project. To validate a recorded report, the existing Playwright entry point remains available: `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_REPORT=/tmp/report.json SAMBEE_E2E_SLICE=publication npm run test:e2e -- viewer-performance-budgets.spec.ts --workers=1`.\n\nSearch/query/navigation probes start in browser event handlers, observe the expected count and active highlight in the existing small search controls, and finish after two frames. They avoid page-wide text queries and Playwright round-trip timing, but aren't hardware input-to-visible-paint measurements. The existing active-search fixture deliberately holds syntax preparation; text-load completion doesn't include syntax. Fresh/cached grammar isolation, first usable text/highlight completion, source editing, large prose/tables, resource acceptance and native interaction still require their own evidence. A passing timing subset isn't full rollout acceptance.\n\nThe browser checks compare exact rendered text, native Select All, selected code text and accessibility-tree output. They also exercise keyboard focus, safe links/HTML, GFM tables/tasks, shared Find navigation, theme-variable updates without text-node replacement, native copy events and Chromium PDF generation. These don't establish OS clipboard payloads, browser-native Find reveal, assistive-technology behavior or visual full-document print/PDF correctness. Those remain manual gates.\n\nThe separate native-constraint slice checks representative multiline, long-line and nested Markdown at widths 1543/390 in Chromium/Firefox. It compares cross-block selected text with a trusted keyboard copy/paste payload, exercises keyboard focus and native `window.find` selection/reveal, and attaches real Chromium PDFs. The native text-find API isn't the browser Find toolbar, and a narrow desktop viewport isn't a physical phone. From `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-native-constraints.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production native Markdown constraints' --workers=1 --reporter=json\n```\n\nFrom the repository root, check the attached PDF text with the existing backend environment:\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-native-constraints.json\n```\n\nThe checker rejects missing/duplicate PDF cases, unsuccessful browser results and missing rendered-document lines. Heading IDs use a safe prefix and standard duplicate/Unicode slugging in the existing HAST pipeline; matching fragments are rewritten consistently. Native and printing matrices have independent checks. Chromium's `window.find` reveal is diagnostic-only because it can select without scrolling even outside Sambee; exact selection remains required in both engines, and Firefox reveal remains enforced. Don't add application scrolling to manufacture a native Find pass.\n\nThe Markdown preview's Print icon calls the native browser print dialog; Save as PDF is a destination in that dialog, not a second renderer or server-side conversion. Print isn't offered in edit mode or enabled while loading has failed or is incomplete. Print-only styles hide controls/background UI, release fullscreen/scroll constraints, wrap code/table cells, retain images and use black text on white regardless of the screen theme. Native `beforeprint`/`afterprint` handlers preserve focus, selection and nested scroll, with pending callbacks removed on disposal. The fullscreen paper sizes against its fixed container rather than dynamic viewport units that can retain print-page dimensions.\n\nRun the independent print matrix from `frontend/`, then inspect the PDF attachments from the repository root:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-markdown-printing.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production Markdown printing' --workers=1 --reporter=json\n```\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-markdown-printing.json --printing\n```\n\nThe 24-case matrix covers three fixtures, both themes, both widths and both engines. It verifies action invocation, print CSS, wrapping/widths and actual Chromium PDF state restoration. The PDF gate requires all 12 Chromium outputs to contain every rendered non-whitespace text line and an embedded image. Clear any forced screen-media override before PDF generation; otherwise Playwright prints screen CSS. First/last-page raster inspection supplements text checks. Firefox CSS checks aren't actual Firefox PDF evidence. Actual Firefox PDF and desktop/physical printing were separately confirmed complete by the user on 2026-10-24; no detailed browser/printer support matrix is inferred. Browser destination, paper, margin and header/footer settings remain user-controlled.\n\nKeep performance changes local to measured costs in the current path. Distinguish first visible syntax from completion of all block preparation, and include serialization and parent updates when measuring typing or atomic replace-all. Configuration-only theme and grammar updates must not request caret reveal or replace the document, selection or editor. Don't add streaming, scheduling abstractions or new edit protocols without evidence that the existing path misses its target.\n\nThe existing viewer harness also has a `production source responsiveness` slice for the 54,000-unit dense and 6,000-match long-line source fixtures. It verifies bounded worker delivery, one atomic replacement, undo/redo, exact saved file bytes and worker termination. Save assertions decode the complete multipart body received by the isolated test HTTP proxy; Playwright's request snapshot can omit uploaded file bytes. All traffic uses fixtures, never stored demo edits.\n\nLarge Replace All operations may temporarily block the editor while CodeMirror applies their atomic change set. This latency is an accepted limitation under D5, not permission to truncate output, split history or replace the entire document instead of preserving logical changes. Text and Markdown editors share an editor-owned indeterminate replacement indicator. Worker preparation shows it only after 200 ms; completion before that threshold cancels it without a flash. Ordinary literal replacements stay synchronous and aren't given an artificial delay.\n\nBefore a known-heavy apply, the indicator is shown and given two animation-frame callbacks so the browser has a paint opportunity before the native dispatch. The conservative workload gate requires at least 1,000 replacements and at least 50,000 UTF-16 units in the source or inserted payload. Literal commands inspect at most 1,000 matches for this estimate; worker commands use the completed change plan. This isn't a duration prediction: some fast workloads may be classified as heavy, and unexpectedly slow synchronous work cannot reveal a delayed indicator while blocking the main thread. Feedback already visible during preparation also receives a paint opportunity before application. There's no minimum visible duration or delayed completion, and the spinner doesn't promise continued animation or input responsiveness during synchronous apply.\n\nThe same command boundary covers toolbar and keyboard Replace All. Pending replacements reject duplicate invocations. Any introduced yield revalidates the exact document, query, selection and writability; editing or switching state cancels obsolete work rather than applying stale replacements. Failure, timeout, cancellation and editor disposal release the indicator, animation, timers and listeners. Hidden documents don't wait indefinitely for throttled animation frames. The status uses the editor theme, exposes accessible busy/status semantics and respects reduced motion; physical assistive-technology behavior remains a separate manual check.\n\nThe `production replacement feedback` slice checks quick no-flash behavior and captures visible feedback with the original source still present, then releases held frames and verifies atomic undo/redo, exact multipart Save and editor cleanup in both engines at widths 1543/390. Its held-frame evidence is functional, not timing acceptance.\n\nSource edits retain one bounded User Timing entry per stage: `sambee:source-editor:serialize`, `sambee:source-editor:publish`, `sambee:source-editor:normalize` and `sambee:source-editor:parent-update`. The enclosing publication includes normalization and the synchronous parent callback. These overlapping stages mustn't be added together. Entries contain lengths/revisions, not document contents. `sambee:source-search:commit` brackets the native atomic dispatch, including its synchronous listeners; deferred React work isn't isolated CPU time inside that measure. The separate click-to-completion probe waits for the parent dirty-state render and two subsequent frames. That boundary is a scheduling proxy, not hardware paint.\n\nFrom `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-responsiveness.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nEach sample attaches source-private measurements and explicit 50 ms atomic-dispatch, enclosing serialization/publication and maximum-timer-gap checks. Missing or invalid evidence fails even without `SAMBEE_E2E_BUDGETS`; that flag additionally enforces the original limits. Retain the failed native atomic-application timing results as diagnostic evidence of the D5 accepted limitation, not as passing samples or a reason to repeat performance-only matrices. Unrelated source timing, worker correctness and resource gates remain required. Transfer counts aren't retained/peak memory evidence, and these fixtures don't establish sustained typing, large-table normalization, dense output expansion or scrolling acceptance.\n\nThe separate `production source typing` slice types 82 characters at a requested 10 ms inter-key delay into each 54,000-unit fixture, without per-key polling. It records trusted browser keydown-to-first/two-frame samples, timer gaps, all four edit stages and optional whole-renderer Long Tasks entries, then verifies exact saved source plus the payload. The `source-typing` attachment enforces two-frame p95 strictly below 50 ms and stage/gap maxima at most 50 ms. All 24 engine/width/repeat trials pass; the worst per-trial p95 is 35 ms. This is a scheduling proxy, not physical input-to-painted-pixel acceptance. Unsupported Long Tasks capability stays unmeasured, and observed tasks wouldn't establish application-owned CPU attribution.\n\nThe `production prose table responsiveness` slice mounts the approved 4,000 formatted paragraphs or 2,400 two-column table rows. It checks every rendered paragraph/cell exactly, preserves native block whitespace, root/text-node identity and full rendered text through 60 programmatic scroll steps, and verifies cross-block native selection and close cleanup. Load timing runs from the browser's file-open click through two frames after all expected blocks mount. The `prose-table-responsiveness` attachment separates load budgets, the earlier two-viewport geometry milestone and diagnostic rAF scroll intervals, including the frame following the final scroll assignment. The final 24 trials complete within 1,110 ms, with the first viewport available within 761 ms. Nineteen trials exceed the unchanged 50 ms timer-gap limit, with a worst gap of 128 ms. These recorded loading pauses are accepted under D6, not passing timing samples or isolated CPU attribution. Headless rAF intervals don't establish physical refresh rate, wheel/touch, compositor or painted-frame acceptance. These fixtures have no fenced syntax and don't measure syntax readiness or large-table source normalization.\n\nThe separate `production progressive Markdown loading cancellation` slice holds frame callbacks after two viewport heights exist. It requires visible feedback, disabled document controls, loading-only print output and a working Close action, then releases stale callbacks and verifies complete reopening. It runs in Chromium and Firefox at widths 1543/390. Its paused screenshots and functional passes aren't timing evidence. The existing large-code publication, native interaction and print matrices remain independent regression checks; their completion and acceptance boundaries are recorded below.\n\nRun these slices separately from forced GC and CPU profiling:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-typing.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source typing' --workers=1 --repeat-each=3 --reporter=json\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-prose-table-responsiveness-final.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production prose table responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nFor separate Chromium load attribution, select the same prose/table slice with `SAMBEE_E2E_TRACE=1` and no budget enforcement or forced GC. The `viewer-load-cpu-profile` and `viewer-load-timeline` attachments span file open through completed mounting; nonempty CPU samples and both `sambee:viewer-load:start`/`sambee:viewer-load:complete` timeline markers are required. Budget status is diagnostic, never acceptance. Two desktop captures show one preview build, with a 126.05 ms prose render callback and a 53.69 ms table callback before native style/layout. The prose clone, transforms and HAST-to-layout-effect stages take 38.3, 37.5 and 44.5 ms; these overlap the encompassing callback and mustn't be added to it. Prose native style/layout takes a further 21.14/38.13 ms. Keep cached-tree isolation and native document semantics; neither deleting the clone nor an unapproved publication/renderer change is justified by this evidence. Firefox/mobile CPU attribution remains unverified.\n\nChromium CPU sample deltas can be negative. Reconstruct cumulative sample timestamps, sort them, then clip nonoverlapping intervals to the load markers. Summing only positive deltas inflates CPU weights. Use the marker's renderer PID/thread for main-thread timeline attribution; worker processing and unclassified native samples aren't automatically application-owned blocking CPU.\n\nRepeated source-regex Next/Previous requests are queued in order while navigation is pending. The active navigation worker reuses its transferred document for that burst, applying each native CodeMirror command from the preceding result's selection with the current position's whole-word rules. It terminates when the queue drains; no idle worker is retained. Document/query changes, external selection changes, replacement commands, failures and disposal cancel obsolete queued navigation. Unit tests compare reused-worker navigation with native commands, including mixed directions, wraparound, overlapping matches and zero-length expressions.\n\nThe independent `production source regex parity` slice compares counts and exact saved output with the installed CodeMirror commands for zero-length lookahead, case-sensitive and whole-word matching. A replacement exceeding two source-transfer chunks verifies continuation assembly without truncation. `production source regex lifecycle` injects worker-construction, error/decode-event and startup-timeout failures, requires actionable feedback and a successful retry, and preserves continued editing and exact Save bytes. A partial-delivery case lets one replacement chunk arrive before cancellation, then replays stale change/completion messages; no partial replacement may be committed. These are host-side fault injections, not actual browser-process crash or structured-clone failure evidence. Run both functional slices with:\n\n```sh\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production source regex (parity|lifecycle)' --workers=1\n```\n\nFor optional source renderer footprint diagnostics, use `SAMBEE_E2E_MEMORY=1` without timing enforcement, select `production source responsiveness`, and run the Chromium-only `npm run test:e2e`. The `source-renderer-memory` attachment records CDP renderer heap after explicit GC at pre-open, counted-results, post-replacement and post-close boundaries. Its historical 64 MiB assertion isn't a release criterion under D11. These are whole-viewer post-GC observations, not isolated result-array bytes, peak/worker/native memory or proof of leak-free cleanup. Staged/peak-memory limits and a fixed close/reopen cycle protocol aren't required. The source budget status is diagnostic in memory mode.\n\nFor a separate Chromium CPU diagnostic, use `SAMBEE_E2E_TRACE=1` without `SAMBEE_E2E_BUDGETS=1`, restrict the grep to `production source responsiveness long-line at 1543px`, and run `npm run test:e2e`. The `source-dispatch-cpu-profile` attachment contains the CDP CPU profile; its source budget status is diagnostic, never an acceptance pass. The source slice rejects combined profiling/GC and either diagnostic mode combined with timing enforcement.\n\nFor separate controlled-memory trials, add `SAMBEE_E2E_MEMORY=1` and restrict the existing matrix to the many-block fixture and Chromium. Release harness-held node references before post-GC sampling. Renderer heap excludes worker heaps and aggregate/native memory; a single close isn't repeated-close leak acceptance. Keep forced GC separate from responsiveness timing.\n\nFor diagnostic scheduling traces, add `SAMBEE_E2E_TRACE=1` to a single-fixture Chromium run. The `viewer-scheduling-trace` attachment contains a CDP timeline and V8 CPU profile. Align `sambee:viewer-trace:start` with browser timestamps; join CPU chunks by renderer PID and profile ID and count samples once. Firefox native profiling must use content-process User Timing markers rather than parent-only samples. Profiling adds overhead and isn't acceptance timing.\n\nTo isolate native table input from application work, run the existing proof from `frontend/`:\n\n```sh\nSAMBEE_NATIVE_TABLE_REPORT=/tmp/sambee-native-table node scripts/source-search-containment-proof.mjs --native-table\n```\n\nThis uses public CodeMirror/Lezer and `markdownTables` APIs at the approved demo URL, with an isolated HTML response and default package styling. It edits the middle cell of the fixed 2,400-row table at 1543x900 without React, application CSS, normalization, Save or workers. It requires exact complete native source, atomic full-table replacement spans, native undo/redo and disposal. Native table source uses `\u003cbr\u003e`; application canonicalization to `\u003cbr /\u003e` isn't part of this proof. Root state materialization and view-update intervals are reported separately; input-to-root includes scheduling and deferred publication, not just model CPU. The unminified desktop diagnostic isn't a production acceptance trial or a replacement for mobile, composition and lifecycle checks.\n\nThe optional report prefix writes per-engine JSON and the exact diagnostic bundle. For separate profiling, add `SAMBEE_E2E_TRACE=1` and configure `MOZ_PROFILER_STARTUP=1`, `MOZ_PROFILER_STARTUP_FILTERS=GeckoMain`, `MOZ_PROFILER_STARTUP_FEATURES=js,stackwalk,leaf` and `MOZ_PROFILER_SHUTDOWN` with an absolute output path. Chromium records input-only CPU samples; clip Firefox content-process samples between `sambee:native-table:input-start` and `sambee:native-table:input-end`, excluding construction and history checks. Profiling requires a report prefix and Firefox startup configuration; product-budget enforcement and controlled-GC modes are rejected. Inclusive model, parsing and native reflow samples overlap and mustn't be summed. Unclassified Chromium native samples aren't automatically package JavaScript CPU. Slow native input doesn't by itself establish slow atomic state application or justify private package patches, changed history, wrapping or selection semantics.\n\nCount assertions remain scoped to the existing search controls to avoid page-wide Playwright text caches inside measurement windows. Results are labelled `scoped-controls-v2`; older input figures aren't directly comparable. Handler-to-frame samples and synthetic event age don't establish hardware input-to-visible-paint latency. Removing the alternate renderer doesn't close any performance, memory or manual interaction gate.\n\n### Shared Highlighting Acceptance And Limitations\n\nThe shared-highlighting implementation was approved by the user for merge and rollout on 2026-10-24. Approval doesn't turn failed measurements into passes or establish support for untested devices. Keep original targets, raw verdicts and these scoped acceptance decisions together:\n\n| Decision | Accepted scope | Boundaries |\n|---|---|---|\n| D5 | Noticeable large atomic Replace All latency with visible busy feedback. | Preserve complete output, logical change mapping, one native transaction and undo/redo. Unrelated source-search or typing pauses aren't accepted by this decision. |\n| D6 | The recorded progressive prose/table preview-loading pauses: 19/24 trials above 50 ms, worst 128 ms; all complete within 1,110 ms. | These remain failed gap samples. Longer future delays and other workloads aren't covered. Asynchronous preview preparation remains declined. |\n| D8 | Responsiveness limitations of the existing Markdown table editor. | Table-component timing is diagnostic and non-blocking; exact input, Save, composition, history and cleanup remain required. |\n| D9 | Ten recorded Firefox many-block syntax-color samples at 1,511-1,579 ms against the 1,500 ms target. | All 120 cold/warm samples were collected; 110 meet that target. Full syntax preparation stays within 3,000 ms. No broader delay exception is implied. |\n| D10 | Four recorded Firefox desktop code-display gaps at 51-59 ms against 50 ms. | Preserve the raw failures. Additional delayed-image/font/resize and scroll-anchor test coverage was removed, not passed. Correct content, selection and scrolling remain required. |\n| D11 | Leak investigation and fixes for demonstrated unwanted retention, rather than quantitative memory acceptance. | Staged/peak-memory limits and fixed-cycle shutdown checks were removed, not passed. No exhaustive leak-free claim is made. |\n| D12 | Removal of real-phone and physical keyboard/IME acceptance, including phone print UI and hardware-response measurements. | This isn't verified device support. Automated keyboard/composition, exact editing/Save/recovery and desktop native/print correctness remain required. |\n\nBrowser-menu Find/reveal, OS clipboard, assistive-technology and physical-scrolling checks were confirmed complete by the user on 2026-10-23. Remaining Firefox PDF and desktop/physical printing checks were confirmed complete on 2026-10-24. These are user confirmations, not new automated measurements or a detailed device, browser, AT or printer support matrix. Don't reopen completed checks or rerun accepted timing failures solely to close a checklist; retest affected behavior after a relevant change or demonstrated regression.\n\nThe final editing checks cover theme changes followed by editing exit and Close, late worker results, distinct documents, captured-revision Save with newer dirty edits, failed writes and recovery/snapshot failures. Source-regex terminal cleanup detaches worker handlers, releases terminated workers and clears obsolete replacement buffers, while retaining buffers needed for a pending atomic apply. Ownership review and lifecycle assertions establish the investigated cleanup, not a heap-retention proof for every browser object.\n\nUse `PLAYWRIGHT_JSON_OUTPUT_FILE`, not `PLAYWRIGHT_JSON_OUTPUT_NAME`, for an explicit report path with the JSON reporter. Preserve complete identities, both engines, widths 1543/390, original workloads and three trials per timing identity. Recorded-report evaluation must retain failed samples and reject missing, duplicate, invalid, skipped or retried identities. Functional-only runs and tracing/GC diagnostics don't establish timing passes. Retain local reports before temporary-file cleanup; overlapping runs aren't additive test totals.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. Dedicated formats need a coordinated backend/frontend contract update. Languages already present in the shared CodeMirror catalogue need no separate extension registration for text opening; extra frontend entries are only needed for MIME or presentation metadata.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/fileLanguages.ts` | reuse shared language filename matching; maintain additional plain-text extensions here rather than duplicating language extensions |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare dedicated viewers and optional MIME/presentation metadata; text-viewer assignments are derived automatically |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or the unified `TextEditor`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npm run typecheck\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/settings-form-dialog-pattern", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "settings-form-dialog-pattern", "title": "Settings Form Dialog Pattern", "path": "developer-guide/frontend-architecture/settings-form-dialog-pattern", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 56, "diff_removed": 26}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 64, "diff_removed": 10}}, "content_versions": {"0.9": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveFormDialog` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveFormDialog` as the shared shell for every ordinary application dialog. It provides the responsive Drawer and Dialog behavior, safe-area action area, dialog surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveFormDialog` with the settings form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveFormDialog` with a single-column settings surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveFormDialog` with compact content and actions. Do not add `SettingsFormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveFormDialog` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveFormDialog` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport the structural primitives and control styles from `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `SettingsFormSurface` | Provides the muted, rounded background and shared interior padding. It darkens the default background by 4% in light mode and lightens it by 8% in dark mode. |\n| `SettingsFormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `SettingsFormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `SettingsFormFieldLabel` | Renders a desktop label with its description or validation error. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `settingsFormFieldControlSx` | Aligns a control to the desktop control column. |\n| `settingsFormSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `settingsFormOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `settingsSelectSx` and `settingsSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveFormDialog` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveFormDialog` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `SettingsFormSurface` and one or more `SettingsFormGroup` components.\n3. Put every field in `SettingsFormRow`.\n4. Use `SettingsFormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; reserve helper-text space when a field can show a validation error.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `SettingsFormRow`.\n\nFor a non-form dialog, start with `ResponsiveFormDialog` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Reserve one helper-text line, then replace it with the active error so the form does not shift. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n\n", "1.0": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse translation strings that describe only what the action will do. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n", "2.0": "+++\ntitle = \"Settings Forms and Actions\"\n+++\n\nUse these conventions for settings pages and stateful settings editors. Pages share section, surface, and action styles. Editors keep the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog without separate mobile and desktop forms.\n\nThe page reference is `frontend/src/pages/LocalDrivesSettings.tsx`; the dialog reference is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the page conventions for settings content and actions. Use the dialog pattern when an editor changes several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use the form pattern for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Settings Page Layout and Actions\n\n`SettingsCategoryContent` loads each settings page on demand. Keep page implementations behind its lazy imports rather than importing them into the application shell. Its local loading and error boundaries leave settings navigation available while a page loads or fails. Permission checks run before an admin page renders or its module starts loading. Changing categories must keep navigation focus aligned and prevent a late module from replacing the newly selected page.\n\nOnce the selected page mounts, prefetch the other permitted pages during idle time through the shared `settingsPageLoaders` registry. The mobile category list starts the same prefetch before a page is selected. Deduplicate background loads, log failures without interrupting navigation, and allow failed loads to retry. Cancel scheduled callbacks when the owning view closes or changes. The desktop dialog resets initial focus for each opening and Strict Mode effect replay, keeping the selected category focused without taking focus away from a form or nested dialog during later updates.\n\nCompose settings pages with `SettingsPage`, `SettingsSectionList`, and `SettingsGroup`. Use `FormSurface` for the subdued background of an action section, not an additional bordered card. For action sections, put the description or metadata on the left and controls on the right in a `FormRow`: the columns stack below `md` and share the row at `md` and above. Right-align actions on desktop, allow them to wrap, and keep result notices below the row. An informational section such as Local Drives' Current status can keep its own layout; don't force it into an action row.\n\nThe Local Drives settings-delivery section uses the shared synchronization lifecycle for all authenticated users. Keep its heading, wrap every status in one `FormSurface`, and put section metadata and Refresh or Retry in a `FormRow`. Notices remain below the row. Do not add a manual Apply control, policy approval prompt, administrator-only status read, or nested surface. Show synchronization failure separately from directory-search health.\n\nChoose button styling by the action's role, not by whether its MUI variant is `outlined` or `contained`:\n\n| Role | Treatment | Example |\n|---|---|---|\n| Regular or secondary | Neutral `settingsUtilityButtonSx`; on a grey `FormSurface`, use `settingsFormSurfaceUtilityButtonSx` so the overlay background shows through, as it does for dialog inputs. Keep the existing border, hover, and keyboard-focus treatment. | Account \u003e Change password; Local Drives \u003e Test Current Pairing. |\n| Danger or alert | Red-tinted `settingsDestructiveButtonSx` for settings-page actions. Use the dialog action rules below for the confirmation. | Local Drives \u003e Unpair This Browser. |\n| Main or default | Prominent `settingsPrimaryButtonSx` for the main action on a grey settings-page surface and for the main action in a page footer or dialog. Avoid giving several routine actions the same emphasis. | Authentication \u003e Configure OIDC; Local Drives \u003e Pair This Browser. |\n\nAdd a relevant `@mui/icons-material` icon with `startIcon` to labeled outlined or contained settings-page action buttons that lack one. Leave text-only buttons, including buttons without an explicit outlined or contained variant, without icons. Adding an icon must not change the button's variant, colors, label, or behavior.\n\n## User Directory Layout\n\nUser Management renders roles and statuses as ordinary text, with each simultaneous status on its own line. Summary counts and removable filters remain badges. Keep column headings and cell values readable: wrap headings, email addresses, usernames, provider names, and other long values without truncating their underlying text. Top-align row contents, and reserve space for sort icons and row actions.\n\nUse the settings content container's width to choose between the desktop grid and stacked records, with a shared 40rem breakpoint for the table and its toolbar. Changing selected columns must not change the layout breakpoint. A narrow settings overlay must stack even on a wide screen. Preserve every selected field when stacking; don't introduce horizontal scrolling or silently hide columns. Show timestamps as a short localized date and time on separate lines, retaining the full timestamp in a tooltip and the original value in a semantic `time` element.\n\nPlace the desktop column chooser icon at the far-right end of the table header, above the row actions. In stacked layouts, place the Columns control at the toolbar's right edge. Keep the toolbar control available while the directory is loading or empty. Anchor the menu to the visible control, reposition it when the settings container resizes, and return focus to the visible control when it closes.\n\nValidate the layout in a real browser with all columns enabled, long identifiers, multiple statuses, different regional formats, narrow containers, mobile widths, and zoom. Component tests don't measure text overlap or container-query behavior.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, and Markdown viewers, and the text editor. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\n## Keyboard Isolation\n\n`ResponsiveDialogShell` establishes a keyboard shortcut scope automatically for both its Drawer and Dialog layouts. While it's open, `useKeyboardShortcuts` ignores background registrations and lets the innermost open dialog own shortcuts, including when a control portals outside the dialog. The shell also stops key events from bubbling into parent workspace handlers. Closing the dialog releases its scope; normal shortcut handling resumes when focus returns to the workspace.\n\nDon't add dialog-specific flags to parent shortcut handlers to provide this isolation. Keep ordinary dialog keyboard behavior in the shell's `onKeyDown` or `onEscape` callbacks. If dialog content needs `useKeyboardShortcuts`, register it in a child component rendered inside the shell so it inherits the dialog's scope, not in the component that creates the shell. Existing focus trapping and interactive-control checks still apply.\n\nEscape dismissal goes through MUI's modal close callback, preserving its top-modal and IME process-key checks. `onEscape`, when supplied, replaces the normal Escape close action and runs once, even when `disableClose` blocks ordinary closing. Use it for cancellation requests during pending operations. Close buttons and backdrop requests still use `onClose` and respect `disableClose`. Don't add document-level Escape listeners or duplicate Escape closing in `onKeyDown`; the shared shell owns that behavior.\n\n## Dialog Action Buttons\n\nChoose each action's treatment by what it does, including in decisions embedded inside full-screen viewers. Keep the viewer workspace shell and toolbars separate from its decision dialogs.\n\n| Role | Treatment | Example |\n|---|---|---|\n| Destructive confirmation | MUI `variant=\"contained\" color=\"error\"`, as in the File delete dialog. Do not use the red-tinted settings-page `settingsDestructiveButtonSx` or introduce another red button style. | Delete, Discard unsaved changes, or Continue with overwrite selected. |\n| Main non-destructive action | MUI `variant=\"contained\"` in the theme's primary color. | Create directory, Save, Retry, or the sole Close action. |\n| Secondary or alternate action | MUI `variant=\"outlined\"` with the existing subdued utility fill and focus treatment. | Cancel, Later, Ignore, or Open without saving. |\n\nAn action's role can change with the selected option: a conflict dialog's Continue is destructive only when it will overwrite an existing item. When a decision offers both Save and Discard, distinguish the primary and destructive actions without changing what either one does. Do not restyle settings-page triggers when styling their confirmation dialogs.\n\nVisual priority does not determine Enter behavior. For safety-critical decisions, focus the least destructive action on opening; for input workflows, focus the first input. Never make a destructive action the default Enter action unless the user has already focused it. Keep cancellation available and focused during cancellable pending operations. Use `ResponsiveDialogShell` for application confirmations rather than native `window.confirm`, whose buttons cannot follow these styles.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- For text inputs and selects with an external label in the left column, use MUI `size=\"small\"` and omit the control's `label` or `InputLabel`. The left-column label is the only visible label; associate it with the control so it remains accessible. Below `md`, restore the control's floating label and normal height.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse translation strings that describe only what the action will do. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor settings-page action sections, check the one-column layout below `md` and the two-column description/action layout at `md` and above. Check neutral-button contrast against grey form surfaces in light and dark themes, including hover and keyboard focus. Check that added icons do not change accessible names or cause button labels to overflow at phone widths. Keep informational sections readable without imposing the action-row grid, and verify that notices remain below the row.\n\nFor dialog actions, check contained error and primary buttons and outlined secondary buttons in light and dark themes, including hover and keyboard focus. Verify that option-dependent destructive actions change treatment without changing their safe initial focus or Enter behavior.\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveFormDialog` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveFormDialog` as the shared shell for every ordinary application dialog. It provides the responsive Drawer and Dialog behavior, safe-area action area, dialog surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveFormDialog` with the settings form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveFormDialog` with a single-column settings surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveFormDialog` with compact content and actions. Do not add `SettingsFormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveFormDialog` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveFormDialog` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport the structural primitives and control styles from `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `SettingsFormSurface` | Provides the muted, rounded background and shared interior padding. It darkens the default background by 4% in light mode and lightens it by 8% in dark mode. |\n| `SettingsFormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `SettingsFormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `SettingsFormFieldLabel` | Renders a desktop label with its description or validation error. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `settingsFormFieldControlSx` | Aligns a control to the desktop control column. |\n| `settingsFormSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `settingsFormOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `settingsSelectSx` and `settingsSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveFormDialog` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveFormDialog` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `SettingsFormSurface` and one or more `SettingsFormGroup` components.\n3. Put every field in `SettingsFormRow`.\n4. Use `SettingsFormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; reserve helper-text space when a field can show a validation error.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `SettingsFormRow`.\n\nFor a non-form dialog, start with `ResponsiveFormDialog` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Reserve one helper-text line, then replace it with the active error so the form does not shift. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n\n", "1.0": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse translation strings that describe only what the action will do. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n", "2.0": "+++\ntitle = \"Settings Forms and Actions\"\n+++\n\nUse these conventions for settings pages and stateful settings editors. Pages share section, surface, and action styles. Editors keep the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog without separate mobile and desktop forms.\n\nThe page reference is `frontend/src/pages/LocalDrivesSettings.tsx`; the dialog reference is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the page conventions for settings content and actions. Use the dialog pattern when an editor changes several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use the form pattern for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Settings Page Layout and Actions\n\n`SettingsCategoryContent` loads each settings page on demand. Keep page implementations behind its lazy imports rather than importing them into the application shell. Its local loading and error boundaries leave settings navigation available while a page loads or fails. Permission checks run before an admin page renders or its module starts loading. Changing categories must keep navigation focus aligned and prevent a late module from replacing the newly selected page.\n\nOnce the selected page mounts, prefetch the other permitted pages during idle time through the shared `settingsPageLoaders` registry. The mobile category list starts the same prefetch before a page is selected. Deduplicate background loads, log failures without interrupting navigation, and allow failed loads to retry. Cancel scheduled callbacks when the owning view closes or changes. The desktop dialog resets initial focus for each opening and Strict Mode effect replay, keeping the selected category focused without taking focus away from a form or nested dialog during later updates.\n\nCompose settings pages with `SettingsPage`, `SettingsSectionList`, and `SettingsGroup`. Use `FormSurface` for the subdued background of an action section, not an additional bordered card. For action sections, put the description or metadata on the left and controls on the right in a `FormRow`: the columns stack below `md` and share the row at `md` and above. Right-align actions on desktop, allow them to wrap, and keep result notices below the row. An informational section such as Local Drives' Current status can keep its own layout; don't force it into an action row.\n\nThe Local Drives settings-delivery section uses the shared synchronization lifecycle for all authenticated users. Keep its heading, wrap every status in one `FormSurface`, and put section metadata and Refresh or Retry in a `FormRow`. Notices remain below the row. Do not add a manual Apply control, policy approval prompt, administrator-only status read, or nested surface. Show synchronization failure separately from directory-search health.\n\nChoose button styling by the action's role, not by whether its MUI variant is `outlined` or `contained`:\n\n| Role | Treatment | Example |\n|---|---|---|\n| Regular or secondary | Neutral `settingsUtilityButtonSx`; on a grey `FormSurface`, use `settingsFormSurfaceUtilityButtonSx` so the overlay background shows through, as it does for dialog inputs. Keep the existing border, hover, and keyboard-focus treatment. | Account \u003e Change password; Local Drives \u003e Test Current Pairing. |\n| Danger or alert | Red-tinted `settingsDestructiveButtonSx` for settings-page actions. Use the dialog action rules below for the confirmation. | Local Drives \u003e Unpair This Browser. |\n| Main or default | Prominent `settingsPrimaryButtonSx` for the main action on a grey settings-page surface and for the main action in a page footer or dialog. Avoid giving several routine actions the same emphasis. | Authentication \u003e Configure OIDC; Local Drives \u003e Pair This Browser. |\n\nAdd a relevant `@mui/icons-material` icon with `startIcon` to labeled outlined or contained settings-page action buttons that lack one. Leave text-only buttons, including buttons without an explicit outlined or contained variant, without icons. Adding an icon must not change the button's variant, colors, label, or behavior.\n\n## User Directory Layout\n\nUser Management renders roles and statuses as ordinary text, with each simultaneous status on its own line. Summary counts and removable filters remain badges. Keep column headings and cell values readable: wrap headings, email addresses, usernames, provider names, and other long values without truncating their underlying text. Top-align row contents, and reserve space for sort icons and row actions.\n\nUse the settings content container's width to choose between the desktop grid and stacked records, with a shared 40rem breakpoint for the table and its toolbar. Changing selected columns must not change the layout breakpoint. A narrow settings overlay must stack even on a wide screen. Preserve every selected field when stacking; don't introduce horizontal scrolling or silently hide columns. Show timestamps as a short localized date and time on separate lines, retaining the full timestamp in a tooltip and the original value in a semantic `time` element.\n\nPlace the desktop column chooser icon at the far-right end of the table header, above the row actions. In stacked layouts, place the Columns control at the toolbar's right edge. Keep the toolbar control available while the directory is loading or empty. Anchor the menu to the visible control, reposition it when the settings container resizes, and return focus to the visible control when it closes.\n\nValidate the layout in a real browser with all columns enabled, long identifiers, multiple statuses, different regional formats, narrow containers, mobile widths, and zoom. Component tests don't measure text overlap or container-query behavior.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, and Markdown viewers, and the text editor. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\n## Keyboard Isolation\n\n`ResponsiveDialogShell` establishes a keyboard shortcut scope automatically for both its Drawer and Dialog layouts. While it's open, `useKeyboardShortcuts` ignores background registrations and lets the innermost open dialog own shortcuts, including when a control portals outside the dialog. The shell also stops key events from bubbling into parent workspace handlers. Closing the dialog releases its scope; normal shortcut handling resumes when focus returns to the workspace.\n\nDon't add dialog-specific flags to parent shortcut handlers to provide this isolation. Keep ordinary dialog keyboard behavior in the shell's `onKeyDown` or `onEscape` callbacks. If dialog content needs `useKeyboardShortcuts`, register it in a child component rendered inside the shell so it inherits the dialog's scope, not in the component that creates the shell. Existing focus trapping and interactive-control checks still apply.\n\nEscape dismissal goes through MUI's modal close callback, preserving its top-modal and IME process-key checks. `onEscape`, when supplied, replaces the normal Escape close action and runs once, even when `disableClose` blocks ordinary closing. Use it for cancellation requests during pending operations. Close buttons and backdrop requests still use `onClose` and respect `disableClose`. Don't add document-level Escape listeners or duplicate Escape closing in `onKeyDown`; the shared shell owns that behavior.\n\n## Dialog Action Buttons\n\nChoose each action's treatment by what it does, including in decisions embedded inside full-screen viewers. Keep the viewer workspace shell and toolbars separate from its decision dialogs.\n\n| Role | Treatment | Example |\n|---|---|---|\n| Destructive confirmation | MUI `variant=\"contained\" color=\"error\"`, as in the File delete dialog. Do not use the red-tinted settings-page `settingsDestructiveButtonSx` or introduce another red button style. | Delete, Discard unsaved changes, or Continue with overwrite selected. |\n| Main non-destructive action | MUI `variant=\"contained\"` in the theme's primary color. | Create directory, Save, Retry, or the sole Close action. |\n| Secondary or alternate action | MUI `variant=\"outlined\"` with the existing subdued utility fill and focus treatment. | Cancel, Later, Ignore, or Open without saving. |\n\nAn action's role can change with the selected option: a conflict dialog's Continue is destructive only when it will overwrite an existing item. When a decision offers both Save and Discard, distinguish the primary and destructive actions without changing what either one does. Do not restyle settings-page triggers when styling their confirmation dialogs.\n\nVisual priority does not determine Enter behavior. For safety-critical decisions, focus the least destructive action on opening; for input workflows, focus the first input. Never make a destructive action the default Enter action unless the user has already focused it. Keep cancellation available and focused during cancellable pending operations. Use `ResponsiveDialogShell` for application confirmations rather than native `window.confirm`, whose buttons cannot follow these styles.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- For text inputs and selects with an external label in the left column, use MUI `size=\"small\"` and omit the control's `label` or `InputLabel`. The left-column label is the only visible label; associate it with the control so it remains accessible. Below `md`, restore the control's floating label and normal height.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse translation strings that describe only what the action will do. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor settings-page action sections, check the one-column layout below `md` and the two-column description/action layout at `md` and above. Check neutral-button contrast against grey form surfaces in light and dark themes, including hover and keyboard focus. Check that added icons do not change accessible names or cause button labels to overflow at phone widths. Keep informational sections readable without imposing the action-row grid, and verify that notices remain below the row.\n\nFor dialog actions, check contained error and primary buttons and outlined secondary buttons in light and dark themes, including hover and keyboard focus. Verify that option-dependent destructive actions change treatment without changing their safe initial focus or Enter behavior.\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/companion-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "companion-architecture", "title": "Companion Architecture", "path": "developer-guide/companion-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "0.8": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "0.9": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "1.0": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "2.0": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/companion-overview", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "companion-overview", "title": "Companion Overview", "path": "developer-guide/companion-architecture/companion-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/companion-runtime-and-native-app-editing", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "companion-runtime-and-native-app-editing", "title": "Companion Runtime And Native App Editing", "path": "developer-guide/companion-architecture/companion-runtime-and-native-app-editing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/browser-to-companion-trust-model", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "browser-to-companion-trust-model", "title": "Browser To Companion Trust Model", "path": "developer-guide/companion-architecture/browser-to-companion-trust-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 8}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 23, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a companion bootstrap token.\n1. Companion uses that bootstrap token to look up file info, acquire the edit lock, receive an operation-scoped token plus lock context, and later upload or release through that narrower edit-session authority.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\nAfter lock acquisition, the browser no longer carries the authority for that edit. The companion holds an operation-scoped backend token plus `operation_id`, `lock_id`, and `lock_capability` for the lifetime of the edit session.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing.\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace explicit pairing with silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, bootstrap tokens, operation tokens, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.8": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.9": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "1.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "2.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Shared Settings Delivery\n\nSuccessful pairing selects the authoritative server for theme, localization, and directory-index resource policy. Pairing again selects that origin again. Failed or cancelled pairing, authenticated status requests, reconnects, and background checks must not change authority. Both native and HTTP unpair paths use `PairingState`; removing the authoritative origin clears authority without selecting a replacement or resetting valid settings.\n\nThe version-1 protocol uses typed `theme`, `localization`, and `directory_index` sections. Theme contains only `id`, `mode`, and `primary.main`. Localization contains stored language and regional-locale preferences, including `browser`. The Companion resolves `browser` from its operating-system webview locale. Directory policy retains its server revision; user sections use SHA-256 digests of canonical payloads and include a user scope.\n\n| Endpoint | Responsibility |\n|---|---|\n| `GET /api/admin/settings/companion` | Authenticated metadata and section markers; not restricted to administrators |\n| `POST /api/admin/settings/companion/grants` | Issue a short-lived, single-use grant for selected sections |\n| `POST /api/admin/settings/companion/grants/redeem` | Direct Companion retrieval of canonical server sections |\n| Companion `GET /api/settings` | Authority and per-section status |\n| Companion `POST /api/settings/challenge` | Authenticated challenge; no extra approval prompt |\n| Companion `POST /api/settings/redeem` | Serialized retrieval and application through the paired authority |\n\nThe browser sends an opaque grant to Companion, not settings payloads. Grants bind origin, Companion ID, challenge, backend identity, user credentials, selected markers, and user-switch permission. Redemption rechecks active user status, credential version, and any issuing OIDC session, then rebuilds selected sections. Changed settings require a fresh grant. Capacity is limited globally and per user. Editing directory policy remains administrator-only.\n\n`CompanionSettingsSync` owns browser synchronization independently of Settings visibility or role. It checks metadata every 30 seconds while visible, compares native markers, and requests a grant only for changed sections. Web Locks serialize work across tabs. Native serialization and marker comparisons make repeated delivery a no-op. Logout and disposal stop work; identity changes cancel stale responses. Pairing, login, and explicit preference changes can change user scope. Background checks and reconnects cannot switch the applied user.\n\nCompanion rechecks authority under its authority lock before committing settings. Directory revisions are ordered only within an origin and backend identity; a new authority or backend identity can start at a lower revision. Supplied sections are validated before application. Per-section failures preserve last valid values and must not report synchronization success. Settings failure is distinct from directory search or index health.\n\nExisting pairings, indexes, and valid policy are retained. Migration selects a still-paired legacy policy binding, or a single legacy pairing. Several unordered legacy pairings require pairing the intended server again. Authority is persisted in the keychain. Old delivery endpoints return an update-required response, not manual policy approval. URI theme delivery is bootstrap-only and cannot override managed settings, including after unpairing.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a companion bootstrap token.\n1. Companion uses that bootstrap token to look up file info, acquire the edit lock, receive an operation-scoped token plus lock context, and later upload or release through that narrower edit-session authority.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\nAfter lock acquisition, the browser no longer carries the authority for that edit. The companion holds an operation-scoped backend token plus `operation_id`, `lock_id`, and `lock_capability` for the lifetime of the edit session.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing.\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace explicit pairing with silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, bootstrap tokens, operation tokens, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.8": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.9": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "1.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "2.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Shared Settings Delivery\n\nSuccessful pairing selects the authoritative server for theme, localization, and directory-index resource policy. Pairing again selects that origin again. Failed or cancelled pairing, authenticated status requests, reconnects, and background checks must not change authority. Both native and HTTP unpair paths use `PairingState`; removing the authoritative origin clears authority without selecting a replacement or resetting valid settings.\n\nThe version-1 protocol uses typed `theme`, `localization`, and `directory_index` sections. Theme contains only `id`, `mode`, and `primary.main`. Localization contains stored language and regional-locale preferences, including `browser`. The Companion resolves `browser` from its operating-system webview locale. Directory policy retains its server revision; user sections use SHA-256 digests of canonical payloads and include a user scope.\n\n| Endpoint | Responsibility |\n|---|---|\n| `GET /api/admin/settings/companion` | Authenticated metadata and section markers; not restricted to administrators |\n| `POST /api/admin/settings/companion/grants` | Issue a short-lived, single-use grant for selected sections |\n| `POST /api/admin/settings/companion/grants/redeem` | Direct Companion retrieval of canonical server sections |\n| Companion `GET /api/settings` | Authority and per-section status |\n| Companion `POST /api/settings/challenge` | Authenticated challenge; no extra approval prompt |\n| Companion `POST /api/settings/redeem` | Serialized retrieval and application through the paired authority |\n\nThe browser sends an opaque grant to Companion, not settings payloads. Grants bind origin, Companion ID, challenge, backend identity, user credentials, selected markers, and user-switch permission. Redemption rechecks active user status, credential version, and any issuing OIDC session, then rebuilds selected sections. Changed settings require a fresh grant. Capacity is limited globally and per user. Editing directory policy remains administrator-only.\n\n`CompanionSettingsSync` owns browser synchronization independently of Settings visibility or role. It checks metadata every 30 seconds while visible, compares native markers, and requests a grant only for changed sections. Web Locks serialize work across tabs. Native serialization and marker comparisons make repeated delivery a no-op. Logout and disposal stop work; identity changes cancel stale responses. Pairing, login, and explicit preference changes can change user scope. Background checks and reconnects cannot switch the applied user.\n\nCompanion rechecks authority under its authority lock before committing settings. Directory revisions are ordered only within an origin and backend identity; a new authority or backend identity can start at a lower revision. Supplied sections are validated before application. Per-section failures preserve last valid values and must not report synchronization success. Settings failure is distinct from directory search or index health.\n\nExisting pairings, indexes, and valid policy are retained. Migration selects a still-paired legacy policy binding, or a single legacy pairing. Several unordered legacy pairings require pairing the intended server again. Authority is persisted in the keychain. Old delivery endpoints return an update-required response, not manual policy approval. URI theme delivery is bootstrap-only and cannot override managed settings, including after unpairing.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/local-drive-and-save-back-pipeline", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "local-drive-and-save-back-pipeline", "title": "Local Drive And Save Back Pipeline", "path": "developer-guide/companion-architecture/local-drive-and-save-back-pipeline", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 16, "diff_removed": 6}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 25, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability and pairing state\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for a bootstrap token\n3. it fetches metadata and conflict baseline information\n4. it acquires the backend edit lock and receives operation-scoped lock context\n5. it downloads the file to a temp directory\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while renewal, heartbeat, and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.8": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.9": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "1.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "2.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nLocalhost bootstrap follows these rules:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Directory-Index Policy Delivery\n\nDirectory policy uses the shared settings protocol described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/#shared-settings-delivery). Pairing selects authority and permits automatic delivery by any active, authenticated user. Only administrators can edit policy. Companion retrieves canonical settings directly from the authoritative backend without redirects.\n\nUpdates serialize against source initialization. Unchanged revisions are no-ops within the same backend identity. Failed delivery or persistence preserves the last valid policy. Authority changes invalidate pending delivery. File APIs must protect policy and index storage from modification. Policy synchronization state is separate from index health.\n\nLocal-drive scans keep committed rows and queued work after interruption or reopen. Child FileIds commit with parent groups and are checked before child traversal. A changed identity requires a fresh parent listing before its children can enter the index. Status polls use memory snapshots; real queries reuse read-only SQLite connections with file-binding checks. Active work prevents idle release, and the shared browser status shows live scan counts.\n\nLinux uses `openat2` when available and no-follow statx checks for directory children. Only ENOSYS disables future `openat2` attempts; permission, link, and mount errors stay errors. The fallback checks each ancestor without following links. Regular files with known entry types need no metadata call; DT_UNKNOWN entries use no-follow metadata before directory checks. Windows uses the shared 1 MiB enumeration buffer. It validates names, attributes, and reparse tags from directory records and preserves full 128-bit FileIds without opening each child. The queued FileId is checked before that child is traversed.\n\nWindows full scans use `OpenFileById` for parents with queued identities. The returned full identity, volume, directory attributes, and exact native path must match. A 64-bit descriptor is used only when it preserves the full stored identity. If FileId opens cannot supply the parent, relative `NtCreateFile` opens it from the retained root. Relative names are validated before I/O; intermediate and final reparse points are rejected. The returned directory must match the root volume and exact native path. The manager defers a replacement identity before its children can be published. Definite unsupported modes are cached per root, with the checked ancestor walk as the final fallback. Permission, redirection, and transport failures remain errors.\n\nEach native scan retains its checked parent descriptor or ancestor chain through enumeration, batch validation, and pruning. With a healthy watcher, commit and child checks use that read without reopening the parent path. On Linux, a missing, failed, or not-yet-ready watcher requires a root-relative parent identity check before each child batch and final parent completion. This check also applies to parallel full-pass and reconciliation reads. Queued identity and observation-token checks still guard writes.\n\nFull passes verify the root when binding and before acceptance. Between these probes, parent reads check the held root locally. Read errors and traversal issues request another full probe before the next parent opens. Version counters preserve requests raised during a probe. Standalone reads and reconciliation keep full root checks. Windows standalone and final ancestor-walk fallback reads retain no-delete ancestor chains; FileId and relative reads retain the parent handle. Held-parent identity and native-path checks run at read boundaries rather than for each record. Non-root full-pass handles permit delete sharing; the root and strict standalone handles retain no-delete sharing.\n\nFull scans and reconciliation read independent parents with at most four worker threads through a bounded channel. Only the scan thread writes. Paged queue reads carry FileIds; ancestor groups commit before descendants start. Both modes use adaptive content/bookkeeping groups and one disk reservation per group. Reconciliation retains strict reads and does not advance the full-verification clock. Item issue counts stay with observation tokens until final snapshot commit; stale tokens discard their counts and leave work pending. Group exit releases buffered ownership, including after an interruption or storage error.\n\nSee [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for shared index rules and [Manage Directory Search](../../../admin-guide/operations-and-maintenance/manage-directory-search/) for the administrator workflow.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nNative watchers do not report deletion of the watched directory on every platform. The companion also checks the target once per second. If the directory is missing or is no longer a directory, the companion removes its watcher state before it sends the change notification. A later subscription can watch a recreated directory.\n\nDirectory requests distinguish a missing path from a path with a file in place of a parent directory. This distinction also applies on Windows, where both cases can produce a missing-path OS error. Only a confirmed missing directory returns `directory_not_found`; a file used as a parent returns `not_a_directory`.\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability and pairing state\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for a bootstrap token\n3. it fetches metadata and conflict baseline information\n4. it acquires the backend edit lock and receives operation-scoped lock context\n5. it downloads the file to a temp directory\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while renewal, heartbeat, and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.8": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.9": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "1.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "2.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nLocalhost bootstrap follows these rules:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Directory-Index Policy Delivery\n\nDirectory policy uses the shared settings protocol described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/#shared-settings-delivery). Pairing selects authority and permits automatic delivery by any active, authenticated user. Only administrators can edit policy. Companion retrieves canonical settings directly from the authoritative backend without redirects.\n\nUpdates serialize against source initialization. Unchanged revisions are no-ops within the same backend identity. Failed delivery or persistence preserves the last valid policy. Authority changes invalidate pending delivery. File APIs must protect policy and index storage from modification. Policy synchronization state is separate from index health.\n\nLocal-drive scans keep committed rows and queued work after interruption or reopen. Child FileIds commit with parent groups and are checked before child traversal. A changed identity requires a fresh parent listing before its children can enter the index. Status polls use memory snapshots; real queries reuse read-only SQLite connections with file-binding checks. Active work prevents idle release, and the shared browser status shows live scan counts.\n\nLinux uses `openat2` when available and no-follow statx checks for directory children. Only ENOSYS disables future `openat2` attempts; permission, link, and mount errors stay errors. The fallback checks each ancestor without following links. Regular files with known entry types need no metadata call; DT_UNKNOWN entries use no-follow metadata before directory checks. Windows uses the shared 1 MiB enumeration buffer. It validates names, attributes, and reparse tags from directory records and preserves full 128-bit FileIds without opening each child. The queued FileId is checked before that child is traversed.\n\nWindows full scans use `OpenFileById` for parents with queued identities. The returned full identity, volume, directory attributes, and exact native path must match. A 64-bit descriptor is used only when it preserves the full stored identity. If FileId opens cannot supply the parent, relative `NtCreateFile` opens it from the retained root. Relative names are validated before I/O; intermediate and final reparse points are rejected. The returned directory must match the root volume and exact native path. The manager defers a replacement identity before its children can be published. Definite unsupported modes are cached per root, with the checked ancestor walk as the final fallback. Permission, redirection, and transport failures remain errors.\n\nEach native scan retains its checked parent descriptor or ancestor chain through enumeration, batch validation, and pruning. With a healthy watcher, commit and child checks use that read without reopening the parent path. On Linux, a missing, failed, or not-yet-ready watcher requires a root-relative parent identity check before each child batch and final parent completion. This check also applies to parallel full-pass and reconciliation reads. Queued identity and observation-token checks still guard writes.\n\nFull passes verify the root when binding and before acceptance. Between these probes, parent reads check the held root locally. Read errors and traversal issues request another full probe before the next parent opens. Version counters preserve requests raised during a probe. Standalone reads and reconciliation keep full root checks. Windows standalone and final ancestor-walk fallback reads retain no-delete ancestor chains; FileId and relative reads retain the parent handle. Held-parent identity and native-path checks run at read boundaries rather than for each record. Non-root full-pass handles permit delete sharing; the root and strict standalone handles retain no-delete sharing.\n\nFull scans and reconciliation read independent parents with at most four worker threads through a bounded channel. Only the scan thread writes. Paged queue reads carry FileIds; ancestor groups commit before descendants start. Both modes use adaptive content/bookkeeping groups and one disk reservation per group. Reconciliation retains strict reads and does not advance the full-verification clock. Item issue counts stay with observation tokens until final snapshot commit; stale tokens discard their counts and leave work pending. Group exit releases buffered ownership, including after an interruption or storage error.\n\nSee [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for shared index rules and [Manage Directory Search](../../../admin-guide/operations-and-maintenance/manage-directory-search/) for the administrator workflow.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nNative watchers do not report deletion of the watched directory on every platform. The companion also checks the target once per second. If the directory is missing or is no longer a directory, the companion removes its watcher state before it sends the change notification. A later subscription can watch a recreated directory.\n\nDirectory requests distinguish a missing path from a path with a file in place of a parent directory. This distinction also applies on Windows, where both cases can produce a missing-path OS error. Only a confirmed missing directory returns `directory_not_found`; a file used as a parent returns `not_a_directory`.\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/cross-cutting-systems", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "cross-cutting-systems", "title": "Cross-Cutting Systems", "path": "developer-guide/cross-cutting-systems", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "0.8": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "0.9": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "1.0": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "2.0": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/logging-and-localization", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "logging-and-localization", "title": "Logging And Localization", "path": "developer-guide/cross-cutting-systems/logging-and-localization", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 43, "diff_removed": 22}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 16, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.8": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.9": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "1.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "2.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n### Directory-Search Diagnostics\n\nUse fixed event names and route templates with status, duration, and counts. Do not log search terms, request payloads, pairing codes, or credentials. Omit paths except for the bounded directory-scan item diagnostics below. Log committed changes only after commit; use numeric error codes instead of exception text that can expose private data.\n\nDirectory scans emit `directory_scan_started`, `directory_scan_finished`, and `directory_scan_invalidated` at INFO. Finish events report committed progress, group commits, duration, and a fixed abort reason. Invalidation events include the reason and a counter, even when the reason repeats. Use these events to distinguish a resumed pass from repeated observation loss. A lifecycle change alone does not require completed parents to be read again.\n\nItem diagnostics use the fixed codes `access_denied`, `unsafe_traversal`, `unsupported_encoding`, and `scan_failed`. The shared `max_logged_scan_issues_per_pass` limit permits at most 20 individual INFO messages in total per pass, with a quoted source path and no private exception text. Restrict access to logs because these messages contain directory names. Pass totals retain all issue counts, including suppressed messages. Backend finish events carry numeric totals; Companion emits `directory_scan_issue_totals` before its finish event. Partial coverage is not a scan abort.\n\nBackend pass logs include `smb_round_trips`, the number of directory-index request groups attempted during the pass. One compound counts once, not once for each message. Root and metadata probes, loop queries, cleanup requests, and credit-growth echoes count separately. Credit admission that rejects a compound without sending it counts zero. Failed send attempts count, so this is not a measurement of completed network exchanges or latency. Ordinary file browsing is not included.\n\nCompanion pass logs include `native_opens`, the number of directory-open attempts made by the source traversal during the pass. The count includes root verification, Linux mount-policy directory checks, fallback traversal, and failed opens. It excludes metadata queries, closes, and index-file I/O. Both counters use per-pass differences from a source-owned total, which survives root rebinding. Start events include the prepared generation, phase, queue counts, and I/O performed during setup. Use the counters to identify repeated opens and probes, and the duration to measure elapsed scan time.\n\nSee [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for lifecycle and storage rules. See [Companion Support Reference](../../../admin-guide/reference/companion-support-reference/#logging-controls) for operational logging controls.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Companion localization uses the shared settings protocol. Deliver stored preferences, including `browser`; Companion resolves them from its own operating-system locale.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser UI formatting uses effective locale values. Shared Companion delivery carries stored preferences, and Companion resolves its own effective locale.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.8": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.9": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "1.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "2.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n### Directory-Search Diagnostics\n\nUse fixed event names and route templates with status, duration, and counts. Do not log search terms, request payloads, pairing codes, or credentials. Omit paths except for the bounded directory-scan item diagnostics below. Log committed changes only after commit; use numeric error codes instead of exception text that can expose private data.\n\nDirectory scans emit `directory_scan_started`, `directory_scan_finished`, and `directory_scan_invalidated` at INFO. Finish events report committed progress, group commits, duration, and a fixed abort reason. Invalidation events include the reason and a counter, even when the reason repeats. Use these events to distinguish a resumed pass from repeated observation loss. A lifecycle change alone does not require completed parents to be read again.\n\nItem diagnostics use the fixed codes `access_denied`, `unsafe_traversal`, `unsupported_encoding`, and `scan_failed`. The shared `max_logged_scan_issues_per_pass` limit permits at most 20 individual INFO messages in total per pass, with a quoted source path and no private exception text. Restrict access to logs because these messages contain directory names. Pass totals retain all issue counts, including suppressed messages. Backend finish events carry numeric totals; Companion emits `directory_scan_issue_totals` before its finish event. Partial coverage is not a scan abort.\n\nBackend pass logs include `smb_round_trips`, the number of directory-index request groups attempted during the pass. One compound counts once, not once for each message. Root and metadata probes, loop queries, cleanup requests, and credit-growth echoes count separately. Credit admission that rejects a compound without sending it counts zero. Failed send attempts count, so this is not a measurement of completed network exchanges or latency. Ordinary file browsing is not included.\n\nCompanion pass logs include `native_opens`, the number of directory-open attempts made by the source traversal during the pass. The count includes root verification, Linux mount-policy directory checks, fallback traversal, and failed opens. It excludes metadata queries, closes, and index-file I/O. Both counters use per-pass differences from a source-owned total, which survives root rebinding. Start events include the prepared generation, phase, queue counts, and I/O performed during setup. Use the counters to identify repeated opens and probes, and the duration to measure elapsed scan time.\n\nSee [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for lifecycle and storage rules. See [Companion Support Reference](../../../admin-guide/reference/companion-support-reference/#logging-controls) for operational logging controls.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Companion localization uses the shared settings protocol. Deliver stored preferences, including `browser`; Companion resolves them from its own operating-system locale.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser UI formatting uses effective locale values. Shared Companion delivery carries stored preferences, and Companion resolves its own effective locale.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/localization-and-locale-behavior", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "localization-and-locale-behavior", "title": "Localization And Locale Behavior", "path": "developer-guide/cross-cutting-systems/localization-and-locale-behavior", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 10, "diff_removed": 8}}, "content_versions": {"0.7": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.8": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.9": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "1.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "2.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nLocalization uses [Shared Settings Delivery](../../companion-architecture/browser-to-companion-trust-model/#shared-settings-delivery) with theme and directory policy. Pairing selects the authoritative server. The backend builds localization from the authenticated user's stored preferences; the browser delivers only a grant.\n\nImportant rules:\n\n- Delivery preserves `browser`. Companion resolves it from its operating-system webview locale, not from the remote browser.\n- Localization has its own canonical payload digest and user scope. An unchanged section is not written again.\n- Pairing, login, and an explicit persisted preference change can change the active user. Periodic checks and reconnects cannot switch users.\n- Rust persists localization atomically, and native windows mirror effective values into local storage for fast startup.\n- Open windows receive localization update events. A new window reads the current native state.\n- The stored update timestamp is diagnostic data, not an ordering credential.\n- A failed section keeps its last valid values and reports delivery failure independently of directory search.\n\nThe separate localhost localization endpoint is retired. Incompatible clients must update; do not restore a parallel synchronizer.\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n"}, "page_contents": {"0.7": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.8": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.9": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "1.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "2.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nLocalization uses [Shared Settings Delivery](../../companion-architecture/browser-to-companion-trust-model/#shared-settings-delivery) with theme and directory policy. Pairing selects the authoritative server. The backend builds localization from the authenticated user's stored preferences; the browser delivers only a grant.\n\nImportant rules:\n\n- Delivery preserves `browser`. Companion resolves it from its operating-system webview locale, not from the remote browser.\n- Localization has its own canonical payload digest and user scope. An unchanged section is not written again.\n- Pairing, login, and an explicit persisted preference change can change the active user. Periodic checks and reconnects cannot switch users.\n- Rust persists localization atomically, and native windows mirror effective values into local storage for fast startup.\n- Open windows receive localization update events. A new window reads the current native state.\n- The stored update timestamp is diagnostic data, not an ordering credential.\n- A failed section keeps its last valid values and reports delivery failure independently of directory search.\n\nThe separate localhost localization endpoint is retired. Incompatible clients must update; do not restore a parallel synchronizer.\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/frontend-logging-and-tracing", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "frontend-logging-and-tracing", "title": "Frontend Logging And Tracing", "path": "developer-guide/cross-cutting-systems/frontend-logging-and-tracing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.8": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.9": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "1.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "2.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.8": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.9": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "1.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "2.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/testing-and-quality-gates", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "testing-and-quality-gates", "title": "Testing and Quality Gates", "path": "developer-guide/testing-and-quality-gates", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "0.8": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "0.9": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "1.0": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "2.0": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/test-strategy-overview", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "test-strategy-overview", "title": "Test Strategy Overview", "path": "developer-guide/testing-and-quality-gates/test-strategy-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 29, "diff_removed": 4}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 8, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, companion, and archive-topology suites together. It stops at the first failed check so you can fix that subsystem before spending time on later suites. The order is backend type checking and tests, frontend type checking, linting, and tests, companion checks and tests, then archive-specific topology verification. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.8": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.9": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "1.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "2.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n### Frontend Console Diagnostics\n\nFrontend Vitest tests fail on every unexpected `console.warn` or `console.error` message, not only known React, MUI, or MSW warnings. The shared test setup records these messages until test cleanup is complete. Clearing or restoring Vitest mocks does not clear recorded diagnostics.\n\nFix the cause of unexpected output. Await asynchronous React updates with `act`, complete pending operations, and unmount components before restoring their API mocks.\n\nIf an error-path test must emit an expected diagnostic, mock that specific message and assert that it occurred. Forward unrelated messages to the original console method. Do not suppress all warnings or errors to make a test pass. Informational `console.log` output is not affected by this policy.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n"}, "page_contents": {"0.7": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, companion, and archive-topology suites together. It stops at the first failed check so you can fix that subsystem before spending time on later suites. The order is backend type checking and tests, frontend type checking, linting, and tests, companion checks and tests, then archive-specific topology verification. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.8": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.9": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "1.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "2.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n### Frontend Console Diagnostics\n\nFrontend Vitest tests fail on every unexpected `console.warn` or `console.error` message, not only known React, MUI, or MSW warnings. The shared test setup records these messages until test cleanup is complete. Clearing or restoring Vitest mocks does not clear recorded diagnostics.\n\nFix the cause of unexpected output. Await asynchronous React updates with `act`, complete pending operations, and unmount components before restoring their API mocks.\n\nIf an error-path test must emit an expected diagnostic, mock that specific message and assert that it occurred. Forward unrelated messages to the original console method. Do not suppress all warnings or errors to make a test pass. Informational `console.log` output is not affected by this policy.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/image-conversion-test-assets", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "image-conversion-test-assets", "title": "Image Conversion Test Assets", "path": "developer-guide/testing-and-quality-gates/image-conversion-test-assets", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.8": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.9": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "1.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "2.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.8": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.9": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "1.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "2.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "ci-workflows-and-repository-automation", "title": "Ci Workflows And Repository Automation", "path": "developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 26, "diff_removed": 2}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 15, "diff_removed": 1}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 47, "diff_removed": 31}}, "content_versions": {"0.7": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n\n", "0.8": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "0.9": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "1.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "2.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Maintenance: Clean Up Actions Caches` | `.github/workflows/cleanup-actions-caches.yml` | Removes closed-PR caches and superseded known cache keys without disabling warm caches for active builds. |\n| `Maintenance: Signal Closed PR Cache Cleanup` | `.github/workflows/signal-closed-pr-cache-cleanup.yml` | Triggers cache cleanup after a pull request closes without granting the pull request write access. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend, including Chromium and Firefox browser correctness\n- companion\n- website documentation\n\nManual dispatch runs all areas. Changes to shared frontend CI infrastructure also select frontend validation.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs. Require `CI: Test / test-gate` in the repository's branch protection or ruleset. A failed browser check fails the selected frontend job and therefore the gate; browser correctness doesn't wait for Docker image creation.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nBackend pytest runs treat unexpected warnings as errors, including resource-cleanup warnings. The shared policy in `backend/pyproject.toml` applies to both local and CI runs, and warning summaries aren't suppressed. Tests that deliberately trigger a warning must assert it with `pytest.warns(...)`, matching the warning category and message. Fix application warnings rather than ignoring them. Unavoidable dependency exceptions must be narrowly scoped and documented; the current exception covers Starlette's TestClient reference to AnyIO's deprecated `BlockingPortal` alias. Remove that exception when the dependency no longer needs it.\n\nThe `frontend` job requires a clean TypeScript check, runs Vitest, builds normal production assets, installs version-matched Playwright Chromium/Firefox binaries and their Linux dependencies, then runs `npm run test:browser:ci`. Both engines run on frontend pull requests, pushes, and manual dispatch. The same required checks run in release fallback when successful source CI cannot be reused.\n\nThe browser command requires exactly 16 production cases: four scenarios at desktop and narrow widths in each engine. They protect real normalization/syntax workers, entity decoding, native selection/focus/heading links/search, regex replacement with undo/redo and exact Save content, and cancellation/reopen cleanup with stale-result replay. Two additional development-worker cases exercise Vite's dependency-resolution path. Browser APIs and workers are real; backend responses are mocked at `http://localhost:3000/browse/smb/demo`. This isn't full-stack SMB E2E or evidence of physical printing, browser-menu Find, hardware IME, or assistive-technology behavior.\n\nThe correctness reporter rejects missing, duplicate, skipped, failed, and retried cases. Browser cases run with one worker and no retries. Reports and retained failure traces/screenshots are uploaded for seven days. Timing budgets, profiling, heap measurements, alternate renderers, and repeated cache/performance matrices remain separate opt-in diagnostics.\n\n`npm run typecheck` runs `tsc -b --noEmit` across the application, test/helper, and Node configuration projects. Browser code uses browser types; tests add Vitest and Node types; configuration tooling uses Node types. All source and declaration files remain checked with strict null/index and unused-code diagnostics enabled. The ES2023 library declarations describe existing APIs; the emitted target remains ES2020, and declarations don't provide runtime polyfills.\n\nType correctness is mandatory in routine CI, release fallback, ordinary `npm run build`, `./scripts/test`, and the VS Code frontend validation task. The old root `tsc --noEmit` command checked no input files and mustn't be used as a substitute. Regression tests protect required command wiring, strict options, separate environments, and complete source coverage. Unit and browser correctness remain independent required gates.\n\nThe required gate rejects an unexpectedly skipped selected job. Only unrelated, unselected areas may be skipped. Superseded pull-request test/lint runs are cancelled; main-branch validation runs aren't cancelled by that policy. Release reuse requires the exact source commit's successful frontend job, its successful browser-correctness step, and the new required `Verify frontend type correctness` step. Missing, skipped, or failed steps and legacy advisory type-check runs don't qualify.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and the archive topology conformance script, including Rust tests, formatting, and Clippy.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- GitHub Actions BuildKit caching for the `backend-test` Docker target, with dependency layers before source copies.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- Rust build caching for `companion/src-tauri`.\n\nFrontend jobs use clean `npm ci --prefer-offline` installs; they don't cache `node_modules` or Playwright browser downloads. The mypy cache inside the disposable backend test container isn't persisted separately.\n\nVitest file parallelism is capped at four workers and further limited by the runner's available CPUs and RAM, reserving 2 GiB plus 2 GiB per worker. The CI command logs the actual resources and selected cap. Standard public Ubuntu runners currently provide 4 vCPUs/16 GB RAM; private runners provide 2 vCPUs/8 GB RAM. Local measurements on a larger machine aren't Actions performance guarantees.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Cache Retention\n\n`Maintenance: Clean Up Actions Caches` runs after cache-producing workflows finish and daily as a fallback. When a pull request closes, an unprivileged signal workflow runs first; its completion triggers the same cleanup. A manual run defaults to a dry run; select **Delete eligible caches** to apply the policy. Its run summary lists selected entries and the amount of storage reclaimed. The cleanup reads only trusted code from `main`, and does not run pull-request code with cache-deletion permissions.\n\nThe policy keeps the newest known cache family on `main` and each open pull request. It removes superseded Rust and website cache keys, and deletes all caches for a closed pull request after its builds finish. It skips refs with active builds and leaves unrecognized keys, including individual BuildKit blobs on active refs, alone. GitHub's normal expiration still applies to those unclassified entries. The job deletes caches by ID so a pull request's copy cannot inadvertently delete an identically keyed cache on `main`.\n\nReview the dry-run report before changing cache-family rules. If active caches alone approach the repository storage limit, raise the limit or accept more cache misses: deleting their newest copies would make CI slower. Cleanup happens after cache uploads, so it cannot prevent a full repository from evicting caches during an upload.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm run test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:ci` for runner-aware Vitest concurrency\n- `cd frontend \u0026\u0026 npm run typecheck` for the complete strict compiler check\n- `cd frontend \u0026\u0026 npm run build` followed by `npm run test:browser:ci` for the exact production/development browser contract\n- `cd frontend \u0026\u0026 npm run test:e2e:install -- --with-deps` to install the matching browsers and Linux dependencies\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nRuff's executable-script rules (`EXE`) also check Python files throughout the repository, including `.github/`. Any Python-file change selects backend lint, as do changes to the lint workflow or `scripts/test`. These checks fail CI and `./scripts/test` on errors; they aren't advisory. A script with a shebang must be executable. Files invoked explicitly through Python, and imported modules, don't need a shebang.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nAll Ubuntu x64 host jobs use `ubuntu-latest`, following GitHub's managed OS migrations and runner-image updates. Native ARM64 image matrices use `ubuntu-26.04-arm`; GitHub doesn't currently document an `ubuntu-latest-arm` label. Windows and macOS coverage remains on its own platform runners.\n\nHost runner choice doesn't replace production-runtime validation. Debian-family checks still include the backend test container and the release `validate-tests` container.\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nThe release `validate-tests` job runs as root and sets `HOME=/root` at job scope. GitHub Actions can otherwise supply a mounted home directory owned by another user, which Firefox refuses to use. The override keeps dependency installation, Playwright browser installation, and browser execution on the same owned home. Hosted frontend PR checks keep the runner's normal home; don't apply `/root` globally or change ownership of GitHub's mounted directories.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n"}, "page_contents": {"0.7": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n\n", "0.8": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "0.9": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "1.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "2.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Maintenance: Clean Up Actions Caches` | `.github/workflows/cleanup-actions-caches.yml` | Removes closed-PR caches and superseded known cache keys without disabling warm caches for active builds. |\n| `Maintenance: Signal Closed PR Cache Cleanup` | `.github/workflows/signal-closed-pr-cache-cleanup.yml` | Triggers cache cleanup after a pull request closes without granting the pull request write access. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend, including Chromium and Firefox browser correctness\n- companion\n- website documentation\n\nManual dispatch runs all areas. Changes to shared frontend CI infrastructure also select frontend validation.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs. Require `CI: Test / test-gate` in the repository's branch protection or ruleset. A failed browser check fails the selected frontend job and therefore the gate; browser correctness doesn't wait for Docker image creation.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nBackend pytest runs treat unexpected warnings as errors, including resource-cleanup warnings. The shared policy in `backend/pyproject.toml` applies to both local and CI runs, and warning summaries aren't suppressed. Tests that deliberately trigger a warning must assert it with `pytest.warns(...)`, matching the warning category and message. Fix application warnings rather than ignoring them. Unavoidable dependency exceptions must be narrowly scoped and documented; the current exception covers Starlette's TestClient reference to AnyIO's deprecated `BlockingPortal` alias. Remove that exception when the dependency no longer needs it.\n\nThe `frontend` job requires a clean TypeScript check, runs Vitest, builds normal production assets, installs version-matched Playwright Chromium/Firefox binaries and their Linux dependencies, then runs `npm run test:browser:ci`. Both engines run on frontend pull requests, pushes, and manual dispatch. The same required checks run in release fallback when successful source CI cannot be reused.\n\nThe browser command requires exactly 16 production cases: four scenarios at desktop and narrow widths in each engine. They protect real normalization/syntax workers, entity decoding, native selection/focus/heading links/search, regex replacement with undo/redo and exact Save content, and cancellation/reopen cleanup with stale-result replay. Two additional development-worker cases exercise Vite's dependency-resolution path. Browser APIs and workers are real; backend responses are mocked at `http://localhost:3000/browse/smb/demo`. This isn't full-stack SMB E2E or evidence of physical printing, browser-menu Find, hardware IME, or assistive-technology behavior.\n\nThe correctness reporter rejects missing, duplicate, skipped, failed, and retried cases. Browser cases run with one worker and no retries. Reports and retained failure traces/screenshots are uploaded for seven days. Timing budgets, profiling, heap measurements, alternate renderers, and repeated cache/performance matrices remain separate opt-in diagnostics.\n\n`npm run typecheck` runs `tsc -b --noEmit` across the application, test/helper, and Node configuration projects. Browser code uses browser types; tests add Vitest and Node types; configuration tooling uses Node types. All source and declaration files remain checked with strict null/index and unused-code diagnostics enabled. The ES2023 library declarations describe existing APIs; the emitted target remains ES2020, and declarations don't provide runtime polyfills.\n\nType correctness is mandatory in routine CI, release fallback, ordinary `npm run build`, `./scripts/test`, and the VS Code frontend validation task. The old root `tsc --noEmit` command checked no input files and mustn't be used as a substitute. Regression tests protect required command wiring, strict options, separate environments, and complete source coverage. Unit and browser correctness remain independent required gates.\n\nThe required gate rejects an unexpectedly skipped selected job. Only unrelated, unselected areas may be skipped. Superseded pull-request test/lint runs are cancelled; main-branch validation runs aren't cancelled by that policy. Release reuse requires the exact source commit's successful frontend job, its successful browser-correctness step, and the new required `Verify frontend type correctness` step. Missing, skipped, or failed steps and legacy advisory type-check runs don't qualify.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and the archive topology conformance script, including Rust tests, formatting, and Clippy.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- GitHub Actions BuildKit caching for the `backend-test` Docker target, with dependency layers before source copies.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- Rust build caching for `companion/src-tauri`.\n\nFrontend jobs use clean `npm ci --prefer-offline` installs; they don't cache `node_modules` or Playwright browser downloads. The mypy cache inside the disposable backend test container isn't persisted separately.\n\nVitest file parallelism is capped at four workers and further limited by the runner's available CPUs and RAM, reserving 2 GiB plus 2 GiB per worker. The CI command logs the actual resources and selected cap. Standard public Ubuntu runners currently provide 4 vCPUs/16 GB RAM; private runners provide 2 vCPUs/8 GB RAM. Local measurements on a larger machine aren't Actions performance guarantees.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Cache Retention\n\n`Maintenance: Clean Up Actions Caches` runs after cache-producing workflows finish and daily as a fallback. When a pull request closes, an unprivileged signal workflow runs first; its completion triggers the same cleanup. A manual run defaults to a dry run; select **Delete eligible caches** to apply the policy. Its run summary lists selected entries and the amount of storage reclaimed. The cleanup reads only trusted code from `main`, and does not run pull-request code with cache-deletion permissions.\n\nThe policy keeps the newest known cache family on `main` and each open pull request. It removes superseded Rust and website cache keys, and deletes all caches for a closed pull request after its builds finish. It skips refs with active builds and leaves unrecognized keys, including individual BuildKit blobs on active refs, alone. GitHub's normal expiration still applies to those unclassified entries. The job deletes caches by ID so a pull request's copy cannot inadvertently delete an identically keyed cache on `main`.\n\nReview the dry-run report before changing cache-family rules. If active caches alone approach the repository storage limit, raise the limit or accept more cache misses: deleting their newest copies would make CI slower. Cleanup happens after cache uploads, so it cannot prevent a full repository from evicting caches during an upload.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm run test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:ci` for runner-aware Vitest concurrency\n- `cd frontend \u0026\u0026 npm run typecheck` for the complete strict compiler check\n- `cd frontend \u0026\u0026 npm run build` followed by `npm run test:browser:ci` for the exact production/development browser contract\n- `cd frontend \u0026\u0026 npm run test:e2e:install -- --with-deps` to install the matching browsers and Linux dependencies\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nRuff's executable-script rules (`EXE`) also check Python files throughout the repository, including `.github/`. Any Python-file change selects backend lint, as do changes to the lint workflow or `scripts/test`. These checks fail CI and `./scripts/test` on errors; they aren't advisory. A script with a shebang must be executable. Files invoked explicitly through Python, and imported modules, don't need a shebang.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nAll Ubuntu x64 host jobs use `ubuntu-latest`, following GitHub's managed OS migrations and runner-image updates. Native ARM64 image matrices use `ubuntu-26.04-arm`; GitHub doesn't currently document an `ubuntu-latest-arm` label. Windows and macOS coverage remains on its own platform runners.\n\nHost runner choice doesn't replace production-runtime validation. Debian-family checks still include the backend test container and the release `validate-tests` container.\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nThe release `validate-tests` job runs as root and sets `HOME=/root` at job scope. GitHub Actions can otherwise supply a mounted home directory owned by another user, which Firefox refuses to use. The override keeps dependency installation, Playwright browser installation, and browser execution on the same owned home. Hosted frontend PR checks keep the runner's normal home; don't apply `/root` globally or change ownership of GitHub's mounted directories.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/contribution-workflows", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "contribution-workflows", "title": "Contribution Workflows", "path": "developer-guide/contribution-workflows", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "0.8": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "0.9": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "1.0": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "2.0": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/contribution-workflows/how-to-plan-and-review-a-change", "parent_id": "section:developer-guide/contribution-workflows", "depth": 2, "kind": "page", "label": "how-to-plan-and-review-a-change", "title": "How To Plan And Review A Change", "path": "developer-guide/contribution-workflows/how-to-plan-and-review-a-change", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.8": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.9": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "1.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "2.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n"}, "page_contents": {"0.7": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.8": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.9": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "1.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "2.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/security", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "security", "title": "Security", "path": "developer-guide/security", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "0.8": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "0.9": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "1.0": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "2.0": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/security/dependency-security-and-dependabot", "parent_id": "section:developer-guide/security", "depth": 2, "kind": "page", "label": "dependency-security-and-dependabot", "title": "Dependency Security And Dependabot", "path": "developer-guide/security/dependency-security-and-dependabot", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 15, "diff_removed": 2}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 3, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.8": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.9": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "1.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "2.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/format-dependabot-pr-title.yml` | prefixes Dependabot pull request titles when configured group names omit them |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nchecks open Dependabot pull requests when a `CI: Test` run triggered by\nDependabot starts and finishes, and adds the matching prefix where needed. It runs trusted workflow code with pull-request write access, without using `pull_request_target` or checking out pull-request code. Run it manually to retry title formatting if a CI run did not trigger it. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.8": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.9": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "1.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "2.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/format-dependabot-pr-title.yml` | prefixes Dependabot pull request titles when configured group names omit them |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nchecks open Dependabot pull requests when a `CI: Test` run triggered by\nDependabot starts and finishes, and adds the matching prefix where needed. It runs trusted workflow code with pull-request write access, without using `pull_request_target` or checking out pull-request code. Run it manually to retry title formatting if a CI run did not trigger it. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/security/container-image-security-and-artifact-integrity", "parent_id": "section:developer-guide/security", "depth": 2, "kind": "page", "label": "container-image-security-and-artifact-integrity", "title": "Container Image Security And Artifact Integrity", "path": "developer-guide/security/container-image-security-and-artifact-integrity", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.8": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.9": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "1.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "2.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n"}, "page_contents": {"0.7": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.8": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.9": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "1.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "2.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/release-and-versioning", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "release-and-versioning", "title": "Release and Versioning", "path": "developer-guide/release-and-versioning", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 2, "diff_removed": 6}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the workflows where a small metadata mistake can create cross-boundary drift.\n\nFor a complete Sambee product release, start here:\n\n- [Release Checklist](./release-checklist/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nUse these pages when the goal is to take one reviewed commit all the way to `stable` without rebuilding at release time.\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n\nUse this section when you are changing version numbers, updating reviewed dependencies, or publishing a product release.\n", "0.8": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the workflows where a small metadata mistake can create cross-boundary drift.\n\nFor a complete Sambee product release, start here:\n\n- [Release Checklist](./release-checklist/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nUse these pages when the goal is to take one reviewed commit all the way to `stable` without rebuilding at release time.\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n\nUse this section when you are changing version numbers, updating reviewed dependencies, or publishing a product release.\n", "0.9": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n", "1.0": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n", "2.0": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/dependency-update-workflow", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "dependency-update-workflow", "title": "Dependency Update Workflow", "path": "developer-guide/release-and-versioning/dependency-update-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 2}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 12, "diff_removed": 14}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 138, "diff_removed": 4}}, "content_versions": {"0.7": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.8": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.9": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "1.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "2.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Frontend Install Freshness\n\n`./scripts/test` checks frontend dependency freshness before generating test\nfixtures or running backend tests. It stops if the install stamp is missing or\ndoesn't match the current `frontend/package.json` and\n`frontend/package-lock.json`. It doesn't install dependencies automatically or\nrequire network access for the check.\n\nTo restore the frontend environment, run this from the repository root:\n\n```bash\ncd frontend \u0026\u0026 npm ci\n```\n\nThe install lifecycle clears any previous stamp before setup and writes a SHA-256\nhash to `frontend/node_modules/.dependencies.sha256` only after the existing\npostinstall setup succeeds. The stamp is local to the installed environment and\nisn't committed. Existing installations need one successful `npm ci` to create\nit. Installations using `--ignore-scripts` won't create the stamp.\n\nTo check the environment separately, run:\n\n```bash\ncd frontend \u0026\u0026 npm run check:dependencies\n```\n\nThe hash covers both files in full, so metadata-only changes also require a fresh\ninstall. This check detects changed dependency inputs, not arbitrary damage to\ninstalled packages. If individual packages are missing despite a matching stamp,\nrun `npm ci` again.\n\n### Biome Version Alignment\n\n`npm run lint` in `frontend/` and `companion/` checks the Biome version before\nlinting source files. Each check requires an exact `@biomejs/biome` pin that\nmatches the lockfile and installed package. Both checks also require matching\npins and lockfile versions in both projects, and matching schemas in the\nrepository-root, frontend, and companion configurations. They don't require the\nother project's installed dependencies.\n\nTo run the checks separately from the repository root:\n\n```bash\nnpm --prefix frontend run check:biome\nnpm --prefix companion run check:biome\n```\n\nKeep both projects on the same Biome version because they share configuration.\nDependabot doesn't update `@biomejs/biome` in either project. Separate npm updates\ncan change a package version without migrating shared configurations. Update\nBiome manually, including security fixes, through this procedure:\n\n1. Set the same exact Biome version in both projects with\n\n\t```bash\n\tnpm --prefix frontend install --save-dev --save-exact @biomejs/biome@\u003cversion\u003e\n\tnpm --prefix companion install --save-dev --save-exact @biomejs/biome@\u003cversion\u003e\n\t```\n\n1. From the repository root, run the installed frontend binary:\n\n\t```bash\n\tfrontend/node_modules/.bin/biome migrate --write\n\t```\n\n1. Review migration requirements for `frontend/biome.json` and\n\t`companion/biome.json`. Apply required setting changes and update their\n\tschemas to the same version. Biome migrates the root configuration but\n\tdoesn't rewrite these non-root configurations. An explicit non-root\n\t`--config-path` is rejected.\n1. Run both `check:biome` commands above and both projects' `npm run lint`.\n1. Include both package manifests, both lockfiles, and all three configurations\n\tin the same change.\n\nIf only the installed version is stale, run `npm ci` in the affected project.\nIf committed pins, locks, or schemas differ, repair them through the coordinated\nprocedure; `npm ci` cannot fix that mismatch. The checks don't install\ndependencies or change configuration files. Dependency security audits still\napply to manually maintained Biome versions.\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. It also\nruns pip with `--dry-run --ignore-installed --require-hashes` for each lockfile.\nThis checks transitive compatibility and hashes without using installed packages\nor changing committed versions. The backend test image and production Docker\nimage validate actual hash-enforced installations.\n\nDependabot doesn't update `pydantic`, `pydantic-core`, or `pydantic-settings`.\nUpdate this package family manually. Pydantic requires an exact core version;\nthe previous core-only ignore rule still allowed Pydantic updates to leave an\nincompatible core pin in both lockfiles. Grouping packages alone doesn't ensure\nthat generated locks contain compatible transitive versions.\n\nFor a Pydantic update or a broken dependency-update pull request:\n\n1. Review and update the direct pins in `backend/requirements.txt` as needed.\n1. Run `scripts/refresh-backend-lockfiles --keep-existing` from the repository root.\n1. Review both generated locks. The resolver keeps existing versions where\n\tcompatible and changes dependencies required by the source pins.\n1. Run backend tests and type checking before merging. Don't force a core pin or\n\tedit its hashes manually.\n\nSecurity findings for this package family need a manual update through the same\nprocedure. The ignore rules don't replace dependency security audits.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests. Add `--keep-existing` to check resolution while keeping compatible\ncommitted versions. This command compares generated file content; it isn't a\nreplacement for the CI pip resolution checks.\n\n### Container Build Pip\n\n`backend/build-tools/requirements.txt` pins the build-time pip version and its\nwheel SHA-256 hash. Keep this file separate from the application lockfiles.\nDependabot checks this directory each week and can update the version and hashes\nin one pull request. Don't copy the pin or download checksum into the Dockerfile.\n\nBefore Python dependency downloads, `scripts/bootstrap-build-pip.py` fetches the\npinned wheel through Python's standard-library HTTPS client and the system CA\nstore. It checks the wheel against the committed hashes, then runs that wheel\ndirectly to install pip offline. The old pip isn't used for the download or\nupgrade. The shared runtime, native `pyvips` wheel builder, and backend-test\nvirtual environment all use this bootstrap step.\n\nThe production target installs the application dependencies, runs `pip check`,\nthen uninstalls pip and removes Python's separate `ensurepip` bootstrap copy.\nThe test, beta, and stable channels use this same production image. They can't\ninstall packages with pip at runtime; change the dependency inputs and rebuild\nthe image instead. Development and backend-test targets keep pip.\n\nThe upgrade and cleanup steps are cached before application source is copied.\nUncached builds need a pip download, but application-only builds can reuse the\ndependency layer. Files from the base image can remain in older image layers,\neven after they're removed from the final filesystem.\n\nFor build-pip updates:\n\n- Run `backend/.venv/bin/python -m pytest backend/tests/test_bootstrap_build_pip_script.py`.\n- Validate startup and the absence of pip, its launchers and metadata, and `ensurepip` in both production image architectures.\n- Run the container vulnerability scan. A pip release can still include vulnerable bundled libraries; a version update alone doesn't prove that all findings are fixed.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm run typecheck \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.8": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.9": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "1.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "2.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Frontend Install Freshness\n\n`./scripts/test` checks frontend dependency freshness before generating test\nfixtures or running backend tests. It stops if the install stamp is missing or\ndoesn't match the current `frontend/package.json` and\n`frontend/package-lock.json`. It doesn't install dependencies automatically or\nrequire network access for the check.\n\nTo restore the frontend environment, run this from the repository root:\n\n```bash\ncd frontend \u0026\u0026 npm ci\n```\n\nThe install lifecycle clears any previous stamp before setup and writes a SHA-256\nhash to `frontend/node_modules/.dependencies.sha256` only after the existing\npostinstall setup succeeds. The stamp is local to the installed environment and\nisn't committed. Existing installations need one successful `npm ci` to create\nit. Installations using `--ignore-scripts` won't create the stamp.\n\nTo check the environment separately, run:\n\n```bash\ncd frontend \u0026\u0026 npm run check:dependencies\n```\n\nThe hash covers both files in full, so metadata-only changes also require a fresh\ninstall. This check detects changed dependency inputs, not arbitrary damage to\ninstalled packages. If individual packages are missing despite a matching stamp,\nrun `npm ci` again.\n\n### Biome Version Alignment\n\n`npm run lint` in `frontend/` and `companion/` checks the Biome version before\nlinting source files. Each check requires an exact `@biomejs/biome` pin that\nmatches the lockfile and installed package. Both checks also require matching\npins and lockfile versions in both projects, and matching schemas in the\nrepository-root, frontend, and companion configurations. They don't require the\nother project's installed dependencies.\n\nTo run the checks separately from the repository root:\n\n```bash\nnpm --prefix frontend run check:biome\nnpm --prefix companion run check:biome\n```\n\nKeep both projects on the same Biome version because they share configuration.\nDependabot doesn't update `@biomejs/biome` in either project. Separate npm updates\ncan change a package version without migrating shared configurations. Update\nBiome manually, including security fixes, through this procedure:\n\n1. Set the same exact Biome version in both projects with\n\n\t```bash\n\tnpm --prefix frontend install --save-dev --save-exact @biomejs/biome@\u003cversion\u003e\n\tnpm --prefix companion install --save-dev --save-exact @biomejs/biome@\u003cversion\u003e\n\t```\n\n1. From the repository root, run the installed frontend binary:\n\n\t```bash\n\tfrontend/node_modules/.bin/biome migrate --write\n\t```\n\n1. Review migration requirements for `frontend/biome.json` and\n\t`companion/biome.json`. Apply required setting changes and update their\n\tschemas to the same version. Biome migrates the root configuration but\n\tdoesn't rewrite these non-root configurations. An explicit non-root\n\t`--config-path` is rejected.\n1. Run both `check:biome` commands above and both projects' `npm run lint`.\n1. Include both package manifests, both lockfiles, and all three configurations\n\tin the same change.\n\nIf only the installed version is stale, run `npm ci` in the affected project.\nIf committed pins, locks, or schemas differ, repair them through the coordinated\nprocedure; `npm ci` cannot fix that mismatch. The checks don't install\ndependencies or change configuration files. Dependency security audits still\napply to manually maintained Biome versions.\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. It also\nruns pip with `--dry-run --ignore-installed --require-hashes` for each lockfile.\nThis checks transitive compatibility and hashes without using installed packages\nor changing committed versions. The backend test image and production Docker\nimage validate actual hash-enforced installations.\n\nDependabot doesn't update `pydantic`, `pydantic-core`, or `pydantic-settings`.\nUpdate this package family manually. Pydantic requires an exact core version;\nthe previous core-only ignore rule still allowed Pydantic updates to leave an\nincompatible core pin in both lockfiles. Grouping packages alone doesn't ensure\nthat generated locks contain compatible transitive versions.\n\nFor a Pydantic update or a broken dependency-update pull request:\n\n1. Review and update the direct pins in `backend/requirements.txt` as needed.\n1. Run `scripts/refresh-backend-lockfiles --keep-existing` from the repository root.\n1. Review both generated locks. The resolver keeps existing versions where\n\tcompatible and changes dependencies required by the source pins.\n1. Run backend tests and type checking before merging. Don't force a core pin or\n\tedit its hashes manually.\n\nSecurity findings for this package family need a manual update through the same\nprocedure. The ignore rules don't replace dependency security audits.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests. Add `--keep-existing` to check resolution while keeping compatible\ncommitted versions. This command compares generated file content; it isn't a\nreplacement for the CI pip resolution checks.\n\n### Container Build Pip\n\n`backend/build-tools/requirements.txt` pins the build-time pip version and its\nwheel SHA-256 hash. Keep this file separate from the application lockfiles.\nDependabot checks this directory each week and can update the version and hashes\nin one pull request. Don't copy the pin or download checksum into the Dockerfile.\n\nBefore Python dependency downloads, `scripts/bootstrap-build-pip.py` fetches the\npinned wheel through Python's standard-library HTTPS client and the system CA\nstore. It checks the wheel against the committed hashes, then runs that wheel\ndirectly to install pip offline. The old pip isn't used for the download or\nupgrade. The shared runtime, native `pyvips` wheel builder, and backend-test\nvirtual environment all use this bootstrap step.\n\nThe production target installs the application dependencies, runs `pip check`,\nthen uninstalls pip and removes Python's separate `ensurepip` bootstrap copy.\nThe test, beta, and stable channels use this same production image. They can't\ninstall packages with pip at runtime; change the dependency inputs and rebuild\nthe image instead. Development and backend-test targets keep pip.\n\nThe upgrade and cleanup steps are cached before application source is copied.\nUncached builds need a pip download, but application-only builds can reuse the\ndependency layer. Files from the base image can remain in older image layers,\neven after they're removed from the final filesystem.\n\nFor build-pip updates:\n\n- Run `backend/.venv/bin/python -m pytest backend/tests/test_bootstrap_build_pip_script.py`.\n- Validate startup and the absence of pip, its launchers and metadata, and `ensurepip` in both production image architectures.\n- Run the container vulnerability scan. A pip release can still include vulnerable bundled libraries; a version update alone doesn't prove that all findings are fixed.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm run typecheck \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/product-versioning", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "product-versioning", "title": "Product Versioning", "path": "developer-guide/release-and-versioning/product-versioning", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 13, "diff_removed": 18}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.8": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.9": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "1.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "2.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.8": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.9": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "1.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "2.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/release-checklist", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "release-checklist", "title": "Release Checklist", "path": "developer-guide/release-and-versioning/release-checklist", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {"0.7": "+++\ntitle = \"Release Checklist\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Release Checklist\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n"}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/docker-release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "docker-release-overview", "title": "Docker Release Overview", "path": "developer-guide/release-and-versioning/docker-release-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 30, "diff_removed": 45}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.8": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.9": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "1.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "2.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.8": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.9": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "1.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "2.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/build-docker-image", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "build-docker-image", "title": "Build Docker Image", "path": "developer-guide/release-and-versioning/build-docker-image", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 23, "diff_removed": 28}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 3, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.8": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.9": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "1.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "2.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow requires the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nFor source checks, the workflow reuses successful backend and frontend jobs from `CI: Test` only when they ran on a push to `main` for the exact candidate commit. It checks each job separately. If a job was skipped, is still running, or its result cannot be verified, the release workflow runs that area's checks itself. PR checks alone do not qualify because they may test a different merge commit. Platform image builds and startup checks always run for a new candidate.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.8": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.9": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "1.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "2.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow requires the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nFor source checks, the workflow reuses successful backend and frontend jobs from `CI: Test` only when they ran on a push to `main` for the exact candidate commit. It checks each job separately. If a job was skipped, is still running, or its result cannot be verified, the release workflow runs that area's checks itself. PR checks alone do not qualify because they may test a different merge commit. Platform image builds and startup checks always run for a new candidate.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/promote-docker-image", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "promote-docker-image", "title": "Promote Docker Image", "path": "developer-guide/release-and-versioning/promote-docker-image", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 32}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.8": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.9": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "1.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "2.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.8": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.9": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "1.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "2.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/docker-backfill-and-cleanup", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "docker-backfill-and-cleanup", "title": "Docker Backfill And Cleanup", "path": "developer-guide/release-and-versioning/docker-backfill-and-cleanup", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.8": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.9": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "1.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "2.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.8": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.9": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "1.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "2.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-release-overview", "title": "Companion Release Overview", "path": "developer-guide/release-and-versioning/companion-release-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 4, "diff_removed": 0}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 25, "diff_removed": 20}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 14, "diff_removed": 47}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 3, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.8": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Local Linux-hosted cross-checks can validate Windows-target compatibility, but they do not replace the Windows CI release build.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.9": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - builds Companion\n   - signs the build artifacts\n   - creates one immutable draft release in in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - assigns a `companion-vX.Y.Z` tag to the draft release.\n1. Test the draft release.\n   - Download the installer from the release's artifacts, install and test.\n1. Publish the draft release. This:\n   - Makes the release eligible for promotion to the `test`, `beta`, and `stable` channels.\n   - Prevents additional build workflow runs changing the published Companion release.\n1. Ensure that a matching published public Sambee release `vX.Y.Z` exists.\n   - This authorizes the Companion workflow to promote a release.\n1. To promote the release to the update channels, run `Release: Promote Companion Release`:\n   - Select the channels: `test`, `beta`, and/or `stable`.\n   - Select whether to update the Sambee download metadata.\n\nThe workflow uses `build`, `recover-finalizer`, and `complete` states. A matching incomplete draft resumes only from recorded retained Actions artifacts; a complete draft or published release is not rebuilt. When a replacement is needed, increment `Z`, synchronize, commit on `main`, and build a new candidate.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set and creates, resumes, or reports the immutable draft GitHub Release in `helgeklein/sambee-companion`. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source and creates or resumes one draft release for its immutable tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Increment the `Z` build sequence when you need another candidate.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "1.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n", "2.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/sambee-app/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.8": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Local Linux-hosted cross-checks can validate Windows-target compatibility, but they do not replace the Windows CI release build.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.9": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - builds Companion\n   - signs the build artifacts\n   - creates one immutable draft release in in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - assigns a `companion-vX.Y.Z` tag to the draft release.\n1. Test the draft release.\n   - Download the installer from the release's artifacts, install and test.\n1. Publish the draft release. This:\n   - Makes the release eligible for promotion to the `test`, `beta`, and `stable` channels.\n   - Prevents additional build workflow runs changing the published Companion release.\n1. Ensure that a matching published public Sambee release `vX.Y.Z` exists.\n   - This authorizes the Companion workflow to promote a release.\n1. To promote the release to the update channels, run `Release: Promote Companion Release`:\n   - Select the channels: `test`, `beta`, and/or `stable`.\n   - Select whether to update the Sambee download metadata.\n\nThe workflow uses `build`, `recover-finalizer`, and `complete` states. A matching incomplete draft resumes only from recorded retained Actions artifacts; a complete draft or published release is not rebuilt. When a replacement is needed, increment `Z`, synchronize, commit on `main`, and build a new candidate.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set and creates, resumes, or reports the immutable draft GitHub Release in `helgeklein/sambee-companion`. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source and creates or resumes one draft release for its immutable tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Increment the `Z` build sequence when you need another candidate.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "1.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n", "2.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/sambee-app/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/build-companion-release", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "build-companion-release", "title": "Build Companion Release", "path": "developer-guide/release-and-versioning/build-companion-release", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 27, "diff_removed": 83}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 25, "diff_removed": 39}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.8": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.9": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create Companion release assets for one immutable build version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It creates builds for the selected platforms, which are then uploaded to the GitHub draft release by a finalizer.\n\n## Input\n\nThe manual workflow exposes an optional existing build-version selector plus one checkbox per platform:\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit with the `build-vX.Y.Z` tag. Leave empty to build the latest commit and set the `build-vX.Y.Z` tag on that commit. |\n| `build_all_platforms` | Include every supported platform in one run. |\n| `build_linux_x64` | Include the Linux x64 build. |\n| `build_macos_arm64` | Include the macOS ARM64 build. |\n| `build_windows_x64` | Include the Windows x64 build. |\n| `build_windows_arm64` | Include the Windows ARM64 build. |\n\nNew builds must be dispatched from `main`. The workflow verifies synchronized metadata, reserves `build-vX.Y.Z` for the exact source commit, and rejects any version that is not plain numeric `X.Y.Z`. It never changes an existing build tag.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the canonical `build-vX.Y.Z` source commit or assigns it to the latest commit.\n3. Verifies synchronized version metadata.\n4. Builds the platform matrix derived from the checked boxes.\n5. Writes a per-platform artifact manifest with package names, SHA-256 checksums, installer/updater/signature roles, platform, and target; then uploads uniquely named private Actions artifacts.\n6. The finalizer downloads every retained artifact, verifies the manifests and complete package sets, writes a public aggregate manifest, provenance, and completion marker, then creates or resumes the external draft release.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Build Output\n\nThe finalizer uploads assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- A public aggregate artifact manifest, uploaded before all package assets.\n- Release provenance and a completion marker binding the release tag, aggregate-manifest digest, provenance digest, and exact expected assets.\n\n### Recovery And Immutability\n\nThe draft GitHub release is immutable once any asset is present: the finalizer uploads a missing asset or accepts an existing byte-identical asset, and rejects a conflicting replacement.\n\nIf a finalizer is interrupted, a later run uses the exact retained Actions artifact IDs, digests, originating run ID, run attempt, platform, and target recorded in draft provenance. It does not rebuild matrix artifacts. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the `companion-release-publication` lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it never reached a publication step.\n\n## Review and Publish\n\nReview the draft GitHub release created or updated by this workflow. Then publish it.\n\nPublishing assigns the tag `companion-vX.Y.Z`.\n", "1.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy.", "2.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy."}, "page_contents": {"0.7": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.8": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.9": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create Companion release assets for one immutable build version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It creates builds for the selected platforms, which are then uploaded to the GitHub draft release by a finalizer.\n\n## Input\n\nThe manual workflow exposes an optional existing build-version selector plus one checkbox per platform:\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit with the `build-vX.Y.Z` tag. Leave empty to build the latest commit and set the `build-vX.Y.Z` tag on that commit. |\n| `build_all_platforms` | Include every supported platform in one run. |\n| `build_linux_x64` | Include the Linux x64 build. |\n| `build_macos_arm64` | Include the macOS ARM64 build. |\n| `build_windows_x64` | Include the Windows x64 build. |\n| `build_windows_arm64` | Include the Windows ARM64 build. |\n\nNew builds must be dispatched from `main`. The workflow verifies synchronized metadata, reserves `build-vX.Y.Z` for the exact source commit, and rejects any version that is not plain numeric `X.Y.Z`. It never changes an existing build tag.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the canonical `build-vX.Y.Z` source commit or assigns it to the latest commit.\n3. Verifies synchronized version metadata.\n4. Builds the platform matrix derived from the checked boxes.\n5. Writes a per-platform artifact manifest with package names, SHA-256 checksums, installer/updater/signature roles, platform, and target; then uploads uniquely named private Actions artifacts.\n6. The finalizer downloads every retained artifact, verifies the manifests and complete package sets, writes a public aggregate manifest, provenance, and completion marker, then creates or resumes the external draft release.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Build Output\n\nThe finalizer uploads assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- A public aggregate artifact manifest, uploaded before all package assets.\n- Release provenance and a completion marker binding the release tag, aggregate-manifest digest, provenance digest, and exact expected assets.\n\n### Recovery And Immutability\n\nThe draft GitHub release is immutable once any asset is present: the finalizer uploads a missing asset or accepts an existing byte-identical asset, and rejects a conflicting replacement.\n\nIf a finalizer is interrupted, a later run uses the exact retained Actions artifact IDs, digests, originating run ID, run attempt, platform, and target recorded in draft provenance. It does not rebuild matrix artifacts. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the `companion-release-publication` lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it never reached a publication step.\n\n## Review and Publish\n\nReview the draft GitHub release created or updated by this workflow. Then publish it.\n\nPublishing assigns the tag `companion-vX.Y.Z`.\n", "1.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy.", "2.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/promote-companion-release", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "promote-companion-release", "title": "Promote Companion Release", "path": "developer-guide/release-and-versioning/promote-companion-release", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 1}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 18, "diff_removed": 16}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 2, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.8": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.9": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nThe workflow reads the selected release's immutable provenance and derives the required public Sambee authorization tag as `vX.Y.Z`. That public release must contain `sambee-release.json` with a matching version, build tag, source SHA, and Companion-compatible scope.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The public `sambee-release.json` does not authorize `companion` or `both`, or its version, build tag, or source SHA differs from the Companion provenance.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow derive the matching public Sambee release, then update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "1.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `helgeklein/sambee-companion`, such as `https://github.com/helgeklein/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "2.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `sambee-app/sambee-companion`, such as `https://github.com/sambee-app/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `sambee-app/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.8": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.9": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nThe workflow reads the selected release's immutable provenance and derives the required public Sambee authorization tag as `vX.Y.Z`. That public release must contain `sambee-release.json` with a matching version, build tag, source SHA, and Companion-compatible scope.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The public `sambee-release.json` does not authorize `companion` or `both`, or its version, build tag, or source SHA differs from the Companion provenance.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow derive the matching public Sambee release, then update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "1.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `helgeklein/sambee-companion`, such as `https://github.com/helgeklein/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "2.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `sambee-app/sambee-companion`, such as `https://github.com/sambee-app/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `sambee-app/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-channels-feeds-and-downloads", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-channels-feeds-and-downloads", "title": "Companion Channels Feeds And Downloads", "path": "developer-guide/release-and-versioning/companion-channels-feeds-and-downloads", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 1}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 6, "diff_removed": 11}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 1, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.8": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.9": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new `Z` version instead.\n- Treat `test`, `beta`, and `stable` as visibility pointers, never as different binaries or version suffixes.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "1.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n", "2.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `sambee-app/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.8": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.9": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new `Z` version instead.\n- Treat `test`, `beta`, and `stable` as visibility pointers, never as different binaries or version suffixes.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "1.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n", "2.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `sambee-app/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "release-overview", "title": "Release Overview", "path": "developer-guide/release-and-versioning/release-overview", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "authored"}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 58, "diff_removed": 21}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 20, "diff_removed": 13}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 2, "diff_removed": 2}}, "content_versions": {"0.8": "+++\ntitle = \"Release Overview\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n", "0.9": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Component Build \u0026 Release Process\n\n### Update Documentation\n\n1. Review the homepage content and update it where necessary.\n1. Docs:\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow creates a draft release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - Publish it.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds `X.Y` a version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `test`, `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "1.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/helgeklein/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "2.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/sambee-app/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/sambee-app/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n"}, "page_contents": {"0.8": "+++\ntitle = \"Release Overview\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n", "0.9": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Component Build \u0026 Release Process\n\n### Update Documentation\n\n1. Review the homepage content and update it where necessary.\n1. Docs:\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow creates a draft release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - Publish it.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds `X.Y` a version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `test`, `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "1.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/helgeklein/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "2.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/sambee-app/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/sambee-app/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-release-cleanup", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-release-cleanup", "title": "Companion Release Cleanup", "path": "developer-guide/release-and-versioning/companion-release-cleanup", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 1, "diff_removed": 2}}, "content_versions": {"1.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `helgeklein/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n\n", "2.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `sambee-app/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n"}, "page_contents": {"1.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `helgeklein/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n\n", "2.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `sambee-app/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "book:website-dev-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "website-dev-guide", "title": "Website Dev Guide", "path": "website-dev-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 0, "diff_removed": 2}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "0.8": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "0.9": "+++\ntitle = \"Website Dev Guide\"\n+++\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "1.0": "+++\ntitle = \"Website Dev Guide\"\n+++\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "2.0": "+++\ntitle = \"Website Dev Guide\"\n+++\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/docs-platform", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "docs-platform", "title": "Docs Platform", "path": "website-dev-guide/docs-platform", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/website-and-docs-architecture-overview", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "website-and-docs-architecture-overview", "title": "Website And Docs Architecture Overview", "path": "website-dev-guide/docs-platform/website-and-docs-architecture-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.8": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.9": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "1.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "2.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.8": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.9": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "1.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "2.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/docs-content-model-navigation-and-inheritance", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "docs-content-model-navigation-and-inheritance", "title": "Docs Content Model Navigation And Inheritance", "path": "website-dev-guide/docs-platform/docs-content-model-navigation-and-inheritance", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.8": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.9": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "1.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "2.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.8": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.9": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "1.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "2.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/docs-runtime-and-route-resolution", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "docs-runtime-and-route-resolution", "title": "Docs Runtime And Route Resolution", "path": "website-dev-guide/docs-platform/docs-runtime-and-route-resolution", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.8": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.9": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "1.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "2.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.8": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.9": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "1.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "2.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/authoring-and-tooling", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "authoring-and-tooling", "title": "Authoring and Tooling", "path": "website-dev-guide/authoring-and-tooling", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-authoring-workflow", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-authoring-workflow", "title": "Docs Authoring Workflow", "path": "website-dev-guide/authoring-and-tooling/docs-authoring-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.8": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.9": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "1.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "2.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n"}, "page_contents": {"0.7": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.8": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.9": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "1.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "2.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-style-guide", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-style-guide", "title": "Docs Style Guide", "path": "website-dev-guide/authoring-and-tooling/docs-style-guide", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.8": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.9": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "1.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "2.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.8": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.9": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "1.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "2.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-shortcodes", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-shortcodes", "title": "Docs Shortcodes", "path": "website-dev-guide/authoring-and-tooling/docs-shortcodes", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.8": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.9": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "1.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "2.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.8": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.9": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "1.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "2.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-editor-tool", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-editor-tool", "title": "Docs Editor Tool", "path": "website-dev-guide/authoring-and-tooling/docs-editor-tool", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 109, "diff_removed": 17}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 37, "diff_removed": 0}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Book\n\nUse this when a book is only a navigation container and should not have a landing page of its own.\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book release-info \\\n  --position start \\\n  --structural-only\n```\n\nThat creates the book directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nInstead:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is a manual content-materialization step, not a page-creation step. The docs editor currently manages page identity and nav structure, but it does not provide a dedicated command that turns an existing inherited page marker into authored page content.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.8": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.9": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "1.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "2.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Book\n\nUse this when a book is only a navigation container and should not have a landing page of its own.\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book release-info \\\n  --position start \\\n  --structural-only\n```\n\nThat creates the book directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nInstead:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is a manual content-materialization step, not a page-creation step. The docs editor currently manages page identity and nav structure, but it does not provide a dedicated command that turns an existing inherited page marker into authored page content.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.8": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.9": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "1.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "2.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-editor-operation-reference", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-editor-operation-reference", "title": "Docs Editor Operation Reference", "path": "website-dev-guide/authoring-and-tooling/docs-editor-operation-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 60, "diff_removed": 4}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 29, "diff_removed": 5}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file. With `--structural-only`, it creates no landing file. `--structural-only` cannot be combined with `--inherit` or `--title`.\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed. It preserves a structural-only book as structural-only; `--title` is not valid when renaming such a book.\n+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen the correct workflow is to materialize real content manually:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis is intentionally outside the scope of `page create`, because the page identity and nav structure already exist.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.8": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.9": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "1.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "2.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n"}, "page_contents": {"0.7": "`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file. With `--structural-only`, it creates no landing file. `--structural-only` cannot be combined with `--inherit` or `--title`.\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed. It preserves a structural-only book as structural-only; `--title` is not valid when renaming such a book.\n+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen the correct workflow is to materialize real content manually:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis is intentionally outside the scope of `page create`, because the page identity and nav structure already exist.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.8": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.9": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "1.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "2.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/site-systems", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "site-systems", "title": "Site Systems", "path": "website-dev-guide/site-systems", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/media-publishing-workflow", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "media-publishing-workflow", "title": "Media Publishing Workflow", "path": "website-dev-guide/site-systems/media-publishing-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.8": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.9": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "1.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "2.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.8": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.9": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "1.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "2.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/typography-system", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "typography-system", "title": "Typography System", "path": "website-dev-guide/site-systems/typography-system", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.8": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.9": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "1.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "2.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n"}, "page_contents": {"0.7": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.8": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.9": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "1.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "2.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/typography-usage-and-boundaries", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "typography-usage-and-boundaries", "title": "Typography Usage And Boundaries", "path": "website-dev-guide/site-systems/typography-usage-and-boundaries", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.8": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.9": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "1.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "2.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.8": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.9": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "1.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "2.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/managed-redirects", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "managed-redirects", "title": "Managed Redirects", "path": "website-dev-guide/site-systems/managed-redirects", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "1.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "2.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "1.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "2.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/setup-and-operations", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "setup-and-operations", "title": "Setup and Operations", "path": "website-dev-guide/setup-and-operations", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing", "parent_id": "section:website-dev-guide/setup-and-operations", "depth": 2, "kind": "page", "label": "set-up-cloudflare-pages-publishing", "title": "Set Up Cloudflare Pages Publishing", "path": "website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.8": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.9": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "1.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "2.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.8": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.9": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "1.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "2.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:release-info", "parent_id": null, "depth": 0, "kind": "book", "label": "release-info", "title": "Release Info", "path": "release-info", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "section:release-info/news-and-changes", "parent_id": "book:release-info", "depth": 1, "kind": "section", "label": "news-and-changes", "title": "News and Changes", "path": "release-info/news-and-changes", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:release-info/news-and-changes/whats-new", "parent_id": "section:release-info/news-and-changes", "depth": 2, "kind": "page", "label": "whats-new", "title": "Whats New", "path": "release-info/news-and-changes/whats-new", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "authored"}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 47, "diff_removed": 46}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 113, "diff_removed": 46}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 186, "diff_removed": 132}}, "content_versions": {"0.8": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar: UX\n\nThe [quick bar](../../../user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar/) is Sambee's main navigation element. It sits in the top bar above the file list and is designed to be the single point of control for directory navigation, file list filtering, and command lookup and execution.\n\nPreviously, those three functions were not clearly distinguished. The three modes are now separated more distinctly, and the current mode is shown directly in the quick bar through a dedicated button. This makes the feature easier to discover and also allows users to switch modes with the mouse or by touch (in addition to the existing keyboard shortcuts).\n\nIn addition, several bugs were fixed to improve the overall experience.\n\n## Companion: More Secure Pairing \u0026 Communication Flows\n\nThis release makes Sambee Companion connections more secure, from the first pairing step through ongoing communication during local-drive access and desktop editing.\n\n**Pairing** is now tracked per Sambee site instead of through one global paired state. Pending approvals can be cancelled cleanly, and the browser now shows clearer states when Companion is unavailable, waiting for local approval, needs repair, or has lost its editing session.\n\nSambee also now trusts only the specific Sambee site you approved, limits what the local Companion service exposes, and uses narrower one-task-at-a-time edit credentials behind the scenes.\n\n**Native editing** is also more resilient. Sambee now uses tighter, task-specific edit permissions, renews long-running edit sessions when needed, and returns you to the browser with a clearer next step if sign-in, lock ownership, or recovery fails, instead of leaving you stuck with a vague error.\n\n## File Opening: Speed \u0026 Flexibility\n\nWhen opening files for previewing or editing, you want quick previews, but you also want the ability to choose which app a file is opened in. Both paths are now efficiently available:\n\nOpen files in Sambee's browser-based viewers:\n\n- Click a file or press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it in Sambee's associated viewer.\n- If no associated viewer exists, or if you press \u003ckbd\u003eShift + Enter\u003c/kbd\u003e, a viewer picker dialog appears.\n   - The picker lets you choose a Sambee browser viewer or a native app.\n\nOpen files in natively installed apps:\n\n- Press \u003ckbd\u003eCtrl + Enter\u003c/kbd\u003e to open a file in its associated native app, or right-click it and select **Open in Native App**.\n- If no associated native app has been chosen, or if you press \u003ckbd\u003eCtrl + Alt + Enter\u003c/kbd\u003e, an app picker dialog appears.\n\n## Markdown Editor: Strategy Change\n\nThe WYSIWYG Markdown editor is gone for a simple reason: UX. There is no open-source rich-text (WYSIWYG) Markdown editor that provides a great user experience. The previous editor was not up to the task.\n\nThe better option is CodeMirror, one of the best available editors, configured for Markdown. It provides a first-rate editing experience and battle-tested add-ons for many of the quality-of-life features people have come to expect from modern editors.\n\n### Interactive Markdown Table Editing\n\nEditing Markdown in a text editor works well for headings and lists, but tables are different. Markdown table syntax is unwieldy, especially when inserting a column in the middle, and the source is difficult to scan. Tables need an interactive WYSIWYG interface that looks and feels like a spreadsheet application. Sambee provides exactly that.\n\n## Text File Viewer and Editor\n\nSince we already have an excellent text editor (see the Markdown Editor note), we might as well put it to good use as a generic text file editor. Sambee can now open, display, and edit any kind of text-based file, with all the bells and whistles of a first-rate editor, for example syntax highlighting.\n\n## Miscellaneous\n\n### Home Screen\n\n- Added a help button next to the settings (gear) icon.\n\n### File List\n\n- Increased the font size on mobile.\n\n### PDF Viewer\n\n- Intra-document links now work correctly, e.g. from a table of contents.\n\n### Under the Hood\n\n- Major dependency upgrades across the board, including React 19 and MUI 9.\n- Improved suspend, resume, and reload resilience.\n\n## Internals\n\n### Documentation System\n\nSambee has a best-in-class documentation system that deduplicates content, inheriting unchanged text copy through versions. This enables us to provide complete and accurate docs for each product version while minimizing maintenance effort.\n\nThis release adds a docs reporting and visualization tool that creates an HTML report of every docs book, section, and page, including its properties, such as whether it is inherited or branched. The report also has a diff view that highlights changes between any two document versions.\n\nDocs editor tool improvements include:\n\n- UI improvements, including better help output.\n- New commands to convert pages between inherited and independent: `page materialize` and `page inherit`.\n- A test and validation suite that also runs in CI.\n", "0.9": "+++\ntitle = \"What's New\"\n+++\n\n## OpenID Connect (OIDC) Authentication and Single Sign-On (SSO)\n\nSingle sign-on was on my list of essential features from the very beginning. Having one source of truth for authentication and authorization is of great benefit even in the smallest networks with single-digit user counts.\n\nSambee includes a secure and comprehensive implementation of OpenID Connect for authentication through IAM servers such as Authelia or Keycloak. If OIDC is configured as the only authentication method, SSO happens behind the scenes and is fully transparent to users who are already logged in to the IAM server. Otherwise, users trying to access Sambee are redirected to the IAM server to authenticate. Once that has happened, they're redirected back to Sambee.\n\nSambee's [OIDC implementation](../../../admin-guide/authentication/openid-connect-authentication-setup/) comes with auto-provisioning, which creates Sambee user accounts automatically after successful OIDC authentication. This can (and often should) be gated by group membership so that only members of a specific group are allowed access to Sambee. Similarly, Sambee's user roles are assigned depending on group membership. This makes it possible to centrally manage access to Sambee's user roles (e.g., admin) in your IAM system.\n\n### Authentication Configuration Change\n\nAuthentication mode is selected only in **Settings** \u003e **Administration** \u003e **Authentication** and defaults to **Password only** for a new installation. The configuration file can only disable enforcement temporarily with `[auth] disable_enforcement = true`; the stored UI mode remains unchanged.\n\nThis is a breaking configuration change. `auth_method` is rejected in both `[auth]` and `[security]`, and existing installations are not migrated automatically. Remove the retired key before upgrading.\n\n## Settings \u0026 Dialogs Overhaul\n\nThe settings got a good UX overhaul that should make them consistent, accessible and, hopefully, much nicer to look at. They're fully responsive, of course, adapting flexibly to phone and desktop screen dimensions. They're also very optimized for efficient keyboard usage while offering touch-friendly sizing on mobile devices.\n\n### New Settings\n\nThe settings also gained several new category pages:\n\n- New personal **Account** settings page\n- New admin **About** settings page\n- New admin **Authentication** settings page\n- New admin **Network** settings page\n- New admin **SMB** settings page\n\nThe about page comes with a feature that may come in handy: creating a **support report** with redacted diagnostic information that's safe to post online.\n\n### User Management Page: Visibility Update\n\nThe user management page in settings was reimplemented to provide significantly better visibility through search, filtering, sorting, summary shortcuts, and a more compact presentation.\n\n### Dialog Look \u0026 Feel\n\nThe refreshed and improved look and feel from settings was applied to the various dialogs that are shown when you copy, move, create, or delete files and/or directories. These dialogs now convey more information in a better way than before.\n\n## Dark Theme Polishing\n\nThe dark theme got a good new coat of paint. The colors of all elements, including backgrounds, text, menus, and dialogs, were tweaked to ensure visual clarity and eye-soothing contrasts.\n\n## Markdown Editor Improvements\n\n- Lists are normalized (formatted) when saved, using `-` for unordered lists and `1.` for every ordered-list item.\n- The editor updates to display the normalized Markdown written to disk after a successful save.\n- Unsaved edits are stored in the browser's local storage so they're not lost when re-authenticating, for example.\n\n## SMB Hardening\n\nTaking a client session isolation bug as a cue, SMB connection handling has been thoroughly hardened. New settings let administrators require Kerberos authentication and SMB 3+ transport encryption. SMBv1 remains disabled and SMB signing is required for every connection.\n\n## Miscellaneous\n\n- **Deleting multiple files** works correctly.\n- The keyboard **shortcuts help** dialog is searchable and resizable.\n\n## Under the Hood\n\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n- Docker container **logging**: severity reclassification\n\n## Internals\n\n### Release Workflow v2: Docker \u0026 Companion Version Lockstep\n\nSambee has a sophisticated build and release system (see the public [docs](../../../developer-guide/release-and-versioning/release-overview/)). Previously, releases and version numbers of the Docker image and the Companion app were deliberately independent. However, it turned out that it's more efficient and natural to increment the versions of both components in sync.\n\nThis led to a significant architectural change that started with a redefinition of the version number ([details](../../../developer-guide/release-and-versioning/product-versioning/)), followed by a second step in which the release processes were reworked to follow a straightforward pattern:\n\n 1. Increment the version number.\n 1. Create a build with that version (Docker image and/or Companion app).\n 1. Promote that build to the `test` channel and test.\n 1. Promote the build to the `beta` and/or `stable` channels.\n\n Crucially, in this new model a build is created only once. Releases happen through promoting existing builds. This guarantees that the version that was tested is exactly what is released later on.\n\n### Docker Dev/Prod Images: Shared Runtime Base Architecture\n\nThe development (devcontainer) and production Docker images are built off a common shared runtime base. This facilitates maintenance and ensures that the shipped image is identical to the environment the developer tested in.\n", "1.0": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar\n\n### File Search\n\nWith the addition of file search (keyboard shortcut: \u003ckbd\u003e/\u003c/kbd\u003e), Sambee's quick bar is becoming a universal search and navigation tool.\n\nFile search complements the existing directory navigation (keyboard shortcut: \u003ckbd\u003eCtrl+K\u003c/kbd\u003e) by providing instant access to recently opened files across directories. File search supersedes file filtering mode, which was removed.\n\n### Directory Navigation History\n\nDirectory navigation now has a history. When you're looking for something, just open the quick bar in directory nav mode and it'll probably already be there. If not, typing a few characters of the name should bring it up in milliseconds.\n\n### Other Changes\n\n- Changed \u003ckbd\u003eF1\u003c/kbd\u003e to consistently invoke keyboard shortcuts help\n\n## Text and Markdown Editors\n\n### Search and Replace\n\nIn any editor, search and replace are essential functions that need to work efficiently while providing granular control. The text and the Markdown editors got just that: compact search and replace popouts with history, regex support and full keyboard usability.\n\n### Other Changes\n\n- Added keyboard shortcuts help\n- Added word wrap (toggled by keyboard shortcut \u003ckbd\u003eAlt+Z\u003c/kbd\u003e)\n- Added viewport scrolling (keyboard shortcut \u003ckbd\u003eCtrl+Arrow up/down\u003c/kbd\u003e)\n- Fixed text selection highlighting\n- Fixed `lock not found or expired` when saving\n\n### Markdown Editor\n\n- Added \u003ckbd\u003eCtrl+B\u003c/kbd\u003e and \u003ckbd\u003eCtrl+I\u003c/kbd\u003e keyboard shortcuts for bold and italic formatting\n\n## PDF Viewer\n\n### More Speed and Higher Fidelity: New Approach to Normalization\n\nEarlier versions normalized every PDF with Ghostscript. This introduced occasional issues and slowed down the viewer. Sambee now opens PDFs in their original form first. When a PDF cannot be displayed because its internal structure is incompatible with the viewer, Sambee can create a separate normalized version for viewing; the original file is never modified. Compatibility processing is limited by file size, processing time, memory, and temporary storage, and each normalized PDF is checked before use.\n\n### Other Changes\n\n- Mobile: swipe to move between pages\n- Encrypted PDFs: the user is now asked to enter a password\n- Large PDFs: better user feedback while loading\n- Color rendering: support for ICC profiles and CMYK\n- Image codecs: support for JPEG 2000 (JXL)\n- Bugfix: geometry changes between pages, e.g., from portrait to landscape, would create endless \"flicker loop\"\n- Bugfix: page rotation commands in the file were not honored\n\n## File List\n\n### ZIP Archive Creation, Inspection, and Extraction\n\nSambee lets you navigate seamlessly into ZIP archives the same way you'd navigate into subdirectories to explore their contents. The UX is instantaneous - only the relevant parts of the ZIP file are decoded. When extracting or compressing, the archive is streamed directly from source to target to minimize CPU, memory, and disk utilization. ZIP operations, like any other, are fully supported across backend boundaries, i.e., between SMB connections and local drives.\n\nThe addition of ZIP archive inspection was the right opportunity to implement storage and content provider abstraction layers. These new abstractions centralize knowledge of storage backends (e.g., SMB, Companion) and how to work with the data on the storage (e.g., regular files, archives), respectively. Introducing these abstractions significantly improves the product's architecture and will greatly simplify adding additional backends or container file types in the future.\n\n### Upload \u0026 Download\n\nA product like Sambee needs efficient ways to get files and folders in and out of the system. To upload files or folders to SMB or local drive destinations, either drag them to Sambee's file browser or select the **Upload** (\u003ckbd\u003eCtrl+U\u003c/kbd\u003e) command in the bottom toolbar. To download files or folders, choose files and/or folders and select the **Download** (\u003ckbd\u003eCtrl+D\u003c/kbd\u003e) command in the bottom toolbar.\n\nDownloading creates a temporary ZIP archive from the selected files and folders, which is then streamed to the browser and subsequently deleted. Sambee allows downloading from all locations: from SMB connections, from local drives, and even from inside ZIP archives.\n\n### Local Drives: Resolve .LNK Files\n\nShortcuts (`.lnk` files), symlinks, and junctions on local drives now show the target path in the status bar. The target information is pulled in asynchronously after the directory list has loaded - we don't want to give up on that snappy UI, after all. Paths are sensibly shortened to fit the available row width.\n\nWhen activated, file targets are opened whereas directory targets are navigated to.\n\n### File Copy and Move: Overwrite Options\n\nCopy and move operations can now overwrite an existing file or replace it only when the source is newer. The same choices work for batches and apply to all supported local and SMB transfers. Directories with the same name are merged safely, preserving destination-only content and resolving only conflicting files.\n\n### Command Toolbar (Desktop) \u0026 Per-Row Actions (Mobile)\n\nA new toolbar at the bottom of the file list makes available commands discoverable. On small screens, typical mobile controls are used instead: a \"+\" icon to create new files or directories and per-row action menus to access commands that operate on individual files or folders.\n\n### Item Selection on Small Screens (Mobile)\n\nOn phones and other small screen devices, files and folders can be selected either through a long press or via the item action menu. Once one item is selected, Sambee switches to multi-selection mode where additional items can be selected through a single tap. An action bar at the bottom of the screen provides access to commands.\n\n### File Metadata on Small Screens (Mobile)\n\nOn phones and other small screen devices, file size and modification time are now displayed in a two-line layout.\n\n### Other Changes\n\n- Added a toolbar button to switch between single-pane and dual-pane modes.\n- When keyboard shortcuts are ignored (because inapplicable in the current situation), Sambee now shows a toast message to make the user unobtrusively aware of the fact.\n- Keyboard navigation: removed delay after entering a new directory.\n- Typeahead buffer: cleared when \u003ckbd\u003eEsc\u003c/kbd\u003e is pressed.\n- The status bar is now always shown.\n\n## Settings\n\n### No More Save Button\n\nClicking a save button at the bottom of the page after adjusting some configuration settings is easily forgotten. So best get rid of that pesky save button altogether. Modern UIs like Sambee's are clever enough to apply config changes automatically and show the user that saving happened through subtle visual cues.\n\n### New Settings\n\nThe settings gained a new category page:\n\n- New admin settings page: **File Search**\n\nFile browser settings:\n\n- **Touch-friendly file selection:** controls how mobile-style file selection is enabled (auto, always on, off).\n\nSystem settings:\n\n- **Temporary archive download size limit:** sets the maximum size of the temporary ZIP archive created when multiple items are downloaded.\n\n### Other Changes\n\n- Localization: Timestamps weren't properly localized in some settings pages (account, user management).\n\n## Image Viewer\n\n- Large images: better user feedback while loading\n\n## Miscellaneous\n\n- Mobile UI: text size increase to improve readability\n- PWA on Chrome on Android: changed the system status bar color from the default blue to gold, matching Sambee's top bar\n- OIDC configuration fields now accept multiple group names as advertised\n- Bugfix: Concurrent OIDC token refreshes would cause SQLite database lock errors.\n- Unicode: file and directory names are normalized to Unicode NFC (single characters) when renamed or created/copied/moved.\n\n## Under the Hood\n\n- Frontend: improved recovery after network unavailability (e.g., after suspend/resume)\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n\n## Internals\n\n### Release Workflow: Companion Alignment with Docker Image\n\nCompanion's release process has been simplified and aligned to match the Docker image workflow:\n\n1. When a new Companion build is created, its GitHub release is published automatically and promoted to the `test` channel.\n1. Interim Companion GitHub releases are deleted automatically when they're no longer needed.\n\n### Other Changes\n\n- Dependency security: The backend's lockfile update process was simplified so that Dependabot can now update lockfiles, too. This removes the need to check out Dependabot PRs locally just to run a lockfile update script.\n", "2.0": "+++\ntitle = \"What's New\"\n+++\n\n## \u26a0\ufe0f Action Required\n\nSambee's GitHub repository was moved to an organization account. This makes it necessary that you update the Docker Compose image URL to `ghcr.io/sambee-app/sambee` in your Docker Compose file (see the [Docker deployment docs](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for details).\n\n## Theme Editor\n\nUI themes are an integral part of an app's visual presentation. As so often, flexibility is key. Some like it dark, others colorful, some require high-contrast, others prefer muted colors.\n\nSambee now has a multi-layer theme system. It differentiates between built-in themes, site-wide themes which only admins can manage, and users' personal themes. Any user can modify existing themes for their own use; admins can also provide themes for other users on the same Sambee server and designate a default theme for new users.\n\nWith Sambee's new theme editor, users can change all theme colors via hex values or the integrated RGBA color picker (which covers transparency in addition to color). Themes can be imported and exported, too.\n\n## File List\n\n### Mouse Selection on Desktop\n\nPrevious versions of Sambee introduced multi-selection for mobile users and keyboard aficionados on desktop. Mouse coverage was lacking. That has been rectified now: Selecting multiple files with a mouse is now straightforward. Click a file or folder icon to select it, then Shift-click another icon to add everything in between without losing your earlier selections. The pane's status bar keeps the count in view.\n\n### New Keyboard Shortcuts\n\n- New tab: \u003ckbd\u003eCtrl+Alt+T\u003c/kbd\u003e opens the current location in a new browser tab.\n- Pane location: \u003ckbd\u003eCtrl+Left\u003c/kbd\u003e sets the left pane to the right pane's location, and \u003ckbd\u003eCtrl+Right\u003c/kbd\u003e sets the right pane to the left pane's location.\n- Item selection: keyboard shortcuts now include \u003ckbd\u003eShift+Home\u003c/kbd\u003e and \u003ckbd\u003eShift+End\u003c/kbd\u003e.\n\n### Other Changes\n\n- Sambee no longer uses \u003ckbd\u003eCtrl+1\u003c/kbd\u003e and \u003ckbd\u003eCtrl+2\u003c/kbd\u003e for pane focus so as not to block these shortcuts for browser tab selection.\n- Native mobile sharing is now available for single or multiple files from the file list.\n- Single-file downloads are now streamed directly without buffering in memory. This speeds up downloads and effectively removes limits imposed by file size.\n\n### Bugfixes\n\n#### File Copy/Move Fixes\n\n- Uploads and copy or move operations no longer interfere with each other's conflict decisions.\n- Moving files between SMB connections no longer leaves the original in place when it should have been deleted.\n- SMB moves now protect the source from concurrent edits and renames, preventing deletion of changes that weren't copied yet.\n- Overwriting an existing SMB file now replaces it atomically instead of failing.\n- Cancelling a move after copying finishes, but before source deletion starts, now correctly reports that both copies were kept.\n- Transfer results now show when a file was copied or replaced, even if removing or checking the original fails.\n- When transferring a folder, a problem with one file no longer hides files already copied, moved, or replaced from the summary.\n- Interrupted SMB moves now release files safely, without leaving them open or interrupting work still in progress.\n- Pressing Enter after a transfer finishes no longer starts the same transfer again.\n- SMB file metadata timezones and ZIP creation now consistently use UTC.\n- SMB connection idle cleanup and failed-request duration logs now use a monotonic clock, so daylight saving time and system clock changes do not affect elapsed-time calculations.\n\n#### SMB Change Monitoring Fixes\n\nFile list:\n\n- File-list monitoring now watches only immediate children, so changes deeper in a folder don't trigger unnecessary refreshes.\n- When changes happen, the file list is now refreshed in the background.\n- File list refreshes are now coalesced and rate-limited.\n\nDirectory cache for instant navigation:\n\n- Quick directory navigation keeps its existing index when a background scan times out or fails.\n- Background scans keep the live directory index when a removal or rename overlaps a read, including when its notification arrives late. This prevents changes from being applied twice when a folder's name is reused.\n- Changing a connection's target or sign-in details no longer reuses directory suggestions from its old configuration.\n- Directory indexing excludes junctions, other reparse descendants, and DFS shares to prevent unsafe traversal.\n- Startup verification and scheduled directory scans now stop cleanly when their cache is removed.\n\n#### Other Fixes\n\n- Invalid file browser URLs no longer break the page or prevent the other pane from loading.\n- Overlapping download requests were allowed.\n- A failed background connection refresh no longer hides a recovered file listing.\n- Renaming a file to a name that differed by case only failed on local drive connections.\n\n## OpenID Connect (OIDC)\n\n### Refresh Token \u0026 `offline_access` Are Now Optional\n\nMany identity providers require the `offline_access` scope to issue refresh tokens, but some (like OneLogin) rejects that scope in the authorization code flow and can issue a refresh token without it when refresh tokens are enabled for the app.\n\nSambee uses a provider refresh token when one is returned, whether or not `offline_access` was requested. If no refresh token is returned, Sambee can continue issuing short-lived API tokens from the browser session for up to 8 hours by default (configurable from 1 to 24 hours). After Sambee's user session expires, the user must sign in through the identity provider again.\n\n### Re-Login Broadcast to Other Open Tabs\n\nWhen an OIDC login is necessary, all Sambee browser tabs switch to the login page. After a successful login in one tab, that tab now broadcasts a login complete hint. When other tabs on the login page receive that hint, they return to their respectice previous URLs.\n\n### Bugfixes\n\n- OIDC login failures after password reset: OIDC login now completes reliably after an administrator resets the account\u2019s password. Sambee ignores responses from the previous browser session while the new login finishes, reloads the user\u2019s themes and settings, and returns to the file browser instead of the login page.\n- Sambee always removed a trailing slash from the issuer URL, which could cause errors with providers like Authentik. Trailing slashes are now left in place.\n\n## Text and Markdown Editors\n\n### Text Viewer and Editor Combined\n\nSambee's text viewer and text editor are now combined into a single component. Text files now open directly in the editor. If write mode cannot be enabled, text editor operates in read-only mode and a notification is shown.\n\nAs part of this change, Sambee got a consistent toast-based notification system for info, warning, and error messages.\n\n### Syntax Highlighting and Rendering Performance Optimization\n\nSambee now uses a consolidated syntax highlighting system throughout all text and Markdown rendering surfaces: text editor, Markdown editor, fenced code blocks in Markdown viewer and Markdown editor. The syntax highlighting system is integrated with the theming system; highlight colors are now part of each theme and can be edited in the new theme editor.\n\nSyntax highlighting is available for a wide range of languages and file types ([docs](../../../user-guide/reference/text-file-support-and-syntax-highlighting/)).\n\nText editor and Markdown editor performance was significantly boosted, especially for long documents. This was achieved through virtualization and viewport rendering.\n\n## Markdown Viewer\n\n### Print and Save as PDF\n\nWhen you print or save as PDF from the browser, the Markdown viewer reformats the full rendered document to fit the page, spanning multiple pages as needed. A new print icon in the top bar makes the new functionality discoverable.\n\n### Other Changes\n\n- Closing the editor by clicking the X now works in the same way as pressing \u003ckbd\u003eEsc\u003c/kbd\u003e: it returns to the viewer. From there, another click returns to the file list.\n- When reloading a browser tab with an editor, Sambee now recovers the file lock. This prevents the error `Unable to enter edit mode. File is locked for editing by \u003cusername\u003e`.\n\n## Quick Bar: Directory Navigation v2\n\nDirectory search and navigation in the quick bar was put on a new foundation:\n\n- Local drives are now indexed, too.\n- The indexing process is now faster and more resilient.\n- The directory index storage was upgraded from JSONL to SQLite databases.\n\n## Miscellaneous\n\n### Native Mobile Sharing\n\nConsolidated the native mobile sharing implementation across the file list and image, PDF, text, and Markdown viewers and editors. When sharing fails, a dialog with details can be invoked to facilitate issue reporting.\n\nText editor and Markdown viewer/editor now have an option to share the current content as text as an alternative to sharing the stored file. This helps circumvent Chrome restrictions that prevent sharing file types such as Markdown.\n\nImage and PDF viewers alway share the displayed content, which may have been normalized for viewing in the browser.\n\n### Full Browser History Navigation\n\nEvery navigation step is now encoded in the URL and recorded in browser history. This enables browser back/forward navigation across the entire Sambee workspace, including the file list, viewers, and editors.\n\n### Local Drive Acess\n\nSambee now checks local-drive access before saying the browser is ready to use Companion. If the check fails, Local Drives settings distinguish between an outdated Companion, an outdated Sambee page, and a pairing that needs to be restored.\n\nWhen Companion rejects a request while browsing a local drive, the file list points to the affected pane and offers a way to reload Sambee or open Local Drives, depending on what went wrong.\n\n### Unencrypted HTTP Support\n\nSambee now deals with unencrypted HTTP explicitly:\n\n- Companion pairing and operations are unavailable.\n- File copying caused a `crypto.randomUUID` error. This has been fixed by implementing a fallback.\n- File uploading would show `outcome uncertain` and not upload files on HTTP/1.1 connections (even over HTTPS). This has been fixed by sending files directly instead of using a streamed request body, so uploads work on HTTP/1.1 while still showing progress.\n- Copying to the clipboard (used in Settings) is now disabled.\n\nHTTP for development on `localhost` is treated as secure by browsers and continues to be supported by Sambee.\n\n### Supported Browser Detection\n\nIf your browser is too old or lacks features Sambee needs, you'll now see a clear message instead of a blank page. The message identifies missing capabilities and links to the browser requirements so you can choose a supported browser.\n\n### Password Login\n\n- When an admin configures a user to require a password change, that change is now enforced upon the next password login.\n- Local usernames are now evaluated case-insensitively.\n- The password field got an option to reveal the password.\n\n### Settings\n\n- User Management: Table column content could overflow into the next row. This was fixes with a comprehensive layout revision.\n\n## Under the Hood\n\n### Security Review\n\nA security review resulted in the following improvements:\n\n- OIDC login now binds the callback and login grant to the browser that started the login flow, preventing a grant from being redeemed in another browser.\n- Only admins can list and download uploaded mobile logs; signed-in users can still upload logs for troubleshooting.\n- Companion requests now use signatures tied to the HTTP method and requested URL, so a signature can't be reused for another request.\n- Mobile log uploads have a size limit, and stored logs are pruned when they exceed the storage budget.\n- HTML, XHTML, and SVG files, including archive members, download instead of running as active content in the viewer.\n\n### Other Changes\n\n- The backend's Python environment was upgraded from 3.13 to 3.14.\n- Fixed the container startup warning: `AuthlibDeprecationWarning: The httpx module is deprecated; please use httpx2 instead.`\n- Reduced the Frontend's JavaScript chunk size.\n\n### Dependency Security\n\n- Updated all dependencies with known issues or vulnerabilities to fixed versions.\n- Pinned all third-party GitHub Actions workflows to commit SHAs.\n- Frontend: removed `patch-package` to get rid of vulnerable transisitve dependency `braces`.\n- Backend: PIP is now upgraded before use and uninstalled from the Docker image afterwards.\n\n### Frontend Type Correctness\n\nType correctness of frontend code and tests is now enforced. As part of this implementation, 1,152 diagnostics across 162 files were fixed: 840 in tests, 311 in application code,\nand one in an imported browser-test helper.\n\n## Internals\n\n- Companion build for Windows: Authenticode signing was removed from PR check builds and only remains on release workflows.\n- GitHub Actions: replaced `pull_request_target` as it will be removed on public repositories by default in November.\n- GitHub Actions: cache retention optimization.\n"}, "page_contents": {"0.8": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar: UX\n\nThe [quick bar](../../../user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar/) is Sambee's main navigation element. It sits in the top bar above the file list and is designed to be the single point of control for directory navigation, file list filtering, and command lookup and execution.\n\nPreviously, those three functions were not clearly distinguished. The three modes are now separated more distinctly, and the current mode is shown directly in the quick bar through a dedicated button. This makes the feature easier to discover and also allows users to switch modes with the mouse or by touch (in addition to the existing keyboard shortcuts).\n\nIn addition, several bugs were fixed to improve the overall experience.\n\n## Companion: More Secure Pairing \u0026 Communication Flows\n\nThis release makes Sambee Companion connections more secure, from the first pairing step through ongoing communication during local-drive access and desktop editing.\n\n**Pairing** is now tracked per Sambee site instead of through one global paired state. Pending approvals can be cancelled cleanly, and the browser now shows clearer states when Companion is unavailable, waiting for local approval, needs repair, or has lost its editing session.\n\nSambee also now trusts only the specific Sambee site you approved, limits what the local Companion service exposes, and uses narrower one-task-at-a-time edit credentials behind the scenes.\n\n**Native editing** is also more resilient. Sambee now uses tighter, task-specific edit permissions, renews long-running edit sessions when needed, and returns you to the browser with a clearer next step if sign-in, lock ownership, or recovery fails, instead of leaving you stuck with a vague error.\n\n## File Opening: Speed \u0026 Flexibility\n\nWhen opening files for previewing or editing, you want quick previews, but you also want the ability to choose which app a file is opened in. Both paths are now efficiently available:\n\nOpen files in Sambee's browser-based viewers:\n\n- Click a file or press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it in Sambee's associated viewer.\n- If no associated viewer exists, or if you press \u003ckbd\u003eShift + Enter\u003c/kbd\u003e, a viewer picker dialog appears.\n   - The picker lets you choose a Sambee browser viewer or a native app.\n\nOpen files in natively installed apps:\n\n- Press \u003ckbd\u003eCtrl + Enter\u003c/kbd\u003e to open a file in its associated native app, or right-click it and select **Open in Native App**.\n- If no associated native app has been chosen, or if you press \u003ckbd\u003eCtrl + Alt + Enter\u003c/kbd\u003e, an app picker dialog appears.\n\n## Markdown Editor: Strategy Change\n\nThe WYSIWYG Markdown editor is gone for a simple reason: UX. There is no open-source rich-text (WYSIWYG) Markdown editor that provides a great user experience. The previous editor was not up to the task.\n\nThe better option is CodeMirror, one of the best available editors, configured for Markdown. It provides a first-rate editing experience and battle-tested add-ons for many of the quality-of-life features people have come to expect from modern editors.\n\n### Interactive Markdown Table Editing\n\nEditing Markdown in a text editor works well for headings and lists, but tables are different. Markdown table syntax is unwieldy, especially when inserting a column in the middle, and the source is difficult to scan. Tables need an interactive WYSIWYG interface that looks and feels like a spreadsheet application. Sambee provides exactly that.\n\n## Text File Viewer and Editor\n\nSince we already have an excellent text editor (see the Markdown Editor note), we might as well put it to good use as a generic text file editor. Sambee can now open, display, and edit any kind of text-based file, with all the bells and whistles of a first-rate editor, for example syntax highlighting.\n\n## Miscellaneous\n\n### Home Screen\n\n- Added a help button next to the settings (gear) icon.\n\n### File List\n\n- Increased the font size on mobile.\n\n### PDF Viewer\n\n- Intra-document links now work correctly, e.g. from a table of contents.\n\n### Under the Hood\n\n- Major dependency upgrades across the board, including React 19 and MUI 9.\n- Improved suspend, resume, and reload resilience.\n\n## Internals\n\n### Documentation System\n\nSambee has a best-in-class documentation system that deduplicates content, inheriting unchanged text copy through versions. This enables us to provide complete and accurate docs for each product version while minimizing maintenance effort.\n\nThis release adds a docs reporting and visualization tool that creates an HTML report of every docs book, section, and page, including its properties, such as whether it is inherited or branched. The report also has a diff view that highlights changes between any two document versions.\n\nDocs editor tool improvements include:\n\n- UI improvements, including better help output.\n- New commands to convert pages between inherited and independent: `page materialize` and `page inherit`.\n- A test and validation suite that also runs in CI.\n", "0.9": "+++\ntitle = \"What's New\"\n+++\n\n## OpenID Connect (OIDC) Authentication and Single Sign-On (SSO)\n\nSingle sign-on was on my list of essential features from the very beginning. Having one source of truth for authentication and authorization is of great benefit even in the smallest networks with single-digit user counts.\n\nSambee includes a secure and comprehensive implementation of OpenID Connect for authentication through IAM servers such as Authelia or Keycloak. If OIDC is configured as the only authentication method, SSO happens behind the scenes and is fully transparent to users who are already logged in to the IAM server. Otherwise, users trying to access Sambee are redirected to the IAM server to authenticate. Once that has happened, they're redirected back to Sambee.\n\nSambee's [OIDC implementation](../../../admin-guide/authentication/openid-connect-authentication-setup/) comes with auto-provisioning, which creates Sambee user accounts automatically after successful OIDC authentication. This can (and often should) be gated by group membership so that only members of a specific group are allowed access to Sambee. Similarly, Sambee's user roles are assigned depending on group membership. This makes it possible to centrally manage access to Sambee's user roles (e.g., admin) in your IAM system.\n\n### Authentication Configuration Change\n\nAuthentication mode is selected only in **Settings** \u003e **Administration** \u003e **Authentication** and defaults to **Password only** for a new installation. The configuration file can only disable enforcement temporarily with `[auth] disable_enforcement = true`; the stored UI mode remains unchanged.\n\nThis is a breaking configuration change. `auth_method` is rejected in both `[auth]` and `[security]`, and existing installations are not migrated automatically. Remove the retired key before upgrading.\n\n## Settings \u0026 Dialogs Overhaul\n\nThe settings got a good UX overhaul that should make them consistent, accessible and, hopefully, much nicer to look at. They're fully responsive, of course, adapting flexibly to phone and desktop screen dimensions. They're also very optimized for efficient keyboard usage while offering touch-friendly sizing on mobile devices.\n\n### New Settings\n\nThe settings also gained several new category pages:\n\n- New personal **Account** settings page\n- New admin **About** settings page\n- New admin **Authentication** settings page\n- New admin **Network** settings page\n- New admin **SMB** settings page\n\nThe about page comes with a feature that may come in handy: creating a **support report** with redacted diagnostic information that's safe to post online.\n\n### User Management Page: Visibility Update\n\nThe user management page in settings was reimplemented to provide significantly better visibility through search, filtering, sorting, summary shortcuts, and a more compact presentation.\n\n### Dialog Look \u0026 Feel\n\nThe refreshed and improved look and feel from settings was applied to the various dialogs that are shown when you copy, move, create, or delete files and/or directories. These dialogs now convey more information in a better way than before.\n\n## Dark Theme Polishing\n\nThe dark theme got a good new coat of paint. The colors of all elements, including backgrounds, text, menus, and dialogs, were tweaked to ensure visual clarity and eye-soothing contrasts.\n\n## Markdown Editor Improvements\n\n- Lists are normalized (formatted) when saved, using `-` for unordered lists and `1.` for every ordered-list item.\n- The editor updates to display the normalized Markdown written to disk after a successful save.\n- Unsaved edits are stored in the browser's local storage so they're not lost when re-authenticating, for example.\n\n## SMB Hardening\n\nTaking a client session isolation bug as a cue, SMB connection handling has been thoroughly hardened. New settings let administrators require Kerberos authentication and SMB 3+ transport encryption. SMBv1 remains disabled and SMB signing is required for every connection.\n\n## Miscellaneous\n\n- **Deleting multiple files** works correctly.\n- The keyboard **shortcuts help** dialog is searchable and resizable.\n\n## Under the Hood\n\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n- Docker container **logging**: severity reclassification\n\n## Internals\n\n### Release Workflow v2: Docker \u0026 Companion Version Lockstep\n\nSambee has a sophisticated build and release system (see the public [docs](../../../developer-guide/release-and-versioning/release-overview/)). Previously, releases and version numbers of the Docker image and the Companion app were deliberately independent. However, it turned out that it's more efficient and natural to increment the versions of both components in sync.\n\nThis led to a significant architectural change that started with a redefinition of the version number ([details](../../../developer-guide/release-and-versioning/product-versioning/)), followed by a second step in which the release processes were reworked to follow a straightforward pattern:\n\n 1. Increment the version number.\n 1. Create a build with that version (Docker image and/or Companion app).\n 1. Promote that build to the `test` channel and test.\n 1. Promote the build to the `beta` and/or `stable` channels.\n\n Crucially, in this new model a build is created only once. Releases happen through promoting existing builds. This guarantees that the version that was tested is exactly what is released later on.\n\n### Docker Dev/Prod Images: Shared Runtime Base Architecture\n\nThe development (devcontainer) and production Docker images are built off a common shared runtime base. This facilitates maintenance and ensures that the shipped image is identical to the environment the developer tested in.\n", "1.0": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar\n\n### File Search\n\nWith the addition of file search (keyboard shortcut: \u003ckbd\u003e/\u003c/kbd\u003e), Sambee's quick bar is becoming a universal search and navigation tool.\n\nFile search complements the existing directory navigation (keyboard shortcut: \u003ckbd\u003eCtrl+K\u003c/kbd\u003e) by providing instant access to recently opened files across directories. File search supersedes file filtering mode, which was removed.\n\n### Directory Navigation History\n\nDirectory navigation now has a history. When you're looking for something, just open the quick bar in directory nav mode and it'll probably already be there. If not, typing a few characters of the name should bring it up in milliseconds.\n\n### Other Changes\n\n- Changed \u003ckbd\u003eF1\u003c/kbd\u003e to consistently invoke keyboard shortcuts help\n\n## Text and Markdown Editors\n\n### Search and Replace\n\nIn any editor, search and replace are essential functions that need to work efficiently while providing granular control. The text and the Markdown editors got just that: compact search and replace popouts with history, regex support and full keyboard usability.\n\n### Other Changes\n\n- Added keyboard shortcuts help\n- Added word wrap (toggled by keyboard shortcut \u003ckbd\u003eAlt+Z\u003c/kbd\u003e)\n- Added viewport scrolling (keyboard shortcut \u003ckbd\u003eCtrl+Arrow up/down\u003c/kbd\u003e)\n- Fixed text selection highlighting\n- Fixed `lock not found or expired` when saving\n\n### Markdown Editor\n\n- Added \u003ckbd\u003eCtrl+B\u003c/kbd\u003e and \u003ckbd\u003eCtrl+I\u003c/kbd\u003e keyboard shortcuts for bold and italic formatting\n\n## PDF Viewer\n\n### More Speed and Higher Fidelity: New Approach to Normalization\n\nEarlier versions normalized every PDF with Ghostscript. This introduced occasional issues and slowed down the viewer. Sambee now opens PDFs in their original form first. When a PDF cannot be displayed because its internal structure is incompatible with the viewer, Sambee can create a separate normalized version for viewing; the original file is never modified. Compatibility processing is limited by file size, processing time, memory, and temporary storage, and each normalized PDF is checked before use.\n\n### Other Changes\n\n- Mobile: swipe to move between pages\n- Encrypted PDFs: the user is now asked to enter a password\n- Large PDFs: better user feedback while loading\n- Color rendering: support for ICC profiles and CMYK\n- Image codecs: support for JPEG 2000 (JXL)\n- Bugfix: geometry changes between pages, e.g., from portrait to landscape, would create endless \"flicker loop\"\n- Bugfix: page rotation commands in the file were not honored\n\n## File List\n\n### ZIP Archive Creation, Inspection, and Extraction\n\nSambee lets you navigate seamlessly into ZIP archives the same way you'd navigate into subdirectories to explore their contents. The UX is instantaneous - only the relevant parts of the ZIP file are decoded. When extracting or compressing, the archive is streamed directly from source to target to minimize CPU, memory, and disk utilization. ZIP operations, like any other, are fully supported across backend boundaries, i.e., between SMB connections and local drives.\n\nThe addition of ZIP archive inspection was the right opportunity to implement storage and content provider abstraction layers. These new abstractions centralize knowledge of storage backends (e.g., SMB, Companion) and how to work with the data on the storage (e.g., regular files, archives), respectively. Introducing these abstractions significantly improves the product's architecture and will greatly simplify adding additional backends or container file types in the future.\n\n### Upload \u0026 Download\n\nA product like Sambee needs efficient ways to get files and folders in and out of the system. To upload files or folders to SMB or local drive destinations, either drag them to Sambee's file browser or select the **Upload** (\u003ckbd\u003eCtrl+U\u003c/kbd\u003e) command in the bottom toolbar. To download files or folders, choose files and/or folders and select the **Download** (\u003ckbd\u003eCtrl+D\u003c/kbd\u003e) command in the bottom toolbar.\n\nDownloading creates a temporary ZIP archive from the selected files and folders, which is then streamed to the browser and subsequently deleted. Sambee allows downloading from all locations: from SMB connections, from local drives, and even from inside ZIP archives.\n\n### Local Drives: Resolve .LNK Files\n\nShortcuts (`.lnk` files), symlinks, and junctions on local drives now show the target path in the status bar. The target information is pulled in asynchronously after the directory list has loaded - we don't want to give up on that snappy UI, after all. Paths are sensibly shortened to fit the available row width.\n\nWhen activated, file targets are opened whereas directory targets are navigated to.\n\n### File Copy and Move: Overwrite Options\n\nCopy and move operations can now overwrite an existing file or replace it only when the source is newer. The same choices work for batches and apply to all supported local and SMB transfers. Directories with the same name are merged safely, preserving destination-only content and resolving only conflicting files.\n\n### Command Toolbar (Desktop) \u0026 Per-Row Actions (Mobile)\n\nA new toolbar at the bottom of the file list makes available commands discoverable. On small screens, typical mobile controls are used instead: a \"+\" icon to create new files or directories and per-row action menus to access commands that operate on individual files or folders.\n\n### Item Selection on Small Screens (Mobile)\n\nOn phones and other small screen devices, files and folders can be selected either through a long press or via the item action menu. Once one item is selected, Sambee switches to multi-selection mode where additional items can be selected through a single tap. An action bar at the bottom of the screen provides access to commands.\n\n### File Metadata on Small Screens (Mobile)\n\nOn phones and other small screen devices, file size and modification time are now displayed in a two-line layout.\n\n### Other Changes\n\n- Added a toolbar button to switch between single-pane and dual-pane modes.\n- When keyboard shortcuts are ignored (because inapplicable in the current situation), Sambee now shows a toast message to make the user unobtrusively aware of the fact.\n- Keyboard navigation: removed delay after entering a new directory.\n- Typeahead buffer: cleared when \u003ckbd\u003eEsc\u003c/kbd\u003e is pressed.\n- The status bar is now always shown.\n\n## Settings\n\n### No More Save Button\n\nClicking a save button at the bottom of the page after adjusting some configuration settings is easily forgotten. So best get rid of that pesky save button altogether. Modern UIs like Sambee's are clever enough to apply config changes automatically and show the user that saving happened through subtle visual cues.\n\n### New Settings\n\nThe settings gained a new category page:\n\n- New admin settings page: **File Search**\n\nFile browser settings:\n\n- **Touch-friendly file selection:** controls how mobile-style file selection is enabled (auto, always on, off).\n\nSystem settings:\n\n- **Temporary archive download size limit:** sets the maximum size of the temporary ZIP archive created when multiple items are downloaded.\n\n### Other Changes\n\n- Localization: Timestamps weren't properly localized in some settings pages (account, user management).\n\n## Image Viewer\n\n- Large images: better user feedback while loading\n\n## Miscellaneous\n\n- Mobile UI: text size increase to improve readability\n- PWA on Chrome on Android: changed the system status bar color from the default blue to gold, matching Sambee's top bar\n- OIDC configuration fields now accept multiple group names as advertised\n- Bugfix: Concurrent OIDC token refreshes would cause SQLite database lock errors.\n- Unicode: file and directory names are normalized to Unicode NFC (single characters) when renamed or created/copied/moved.\n\n## Under the Hood\n\n- Frontend: improved recovery after network unavailability (e.g., after suspend/resume)\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n\n## Internals\n\n### Release Workflow: Companion Alignment with Docker Image\n\nCompanion's release process has been simplified and aligned to match the Docker image workflow:\n\n1. When a new Companion build is created, its GitHub release is published automatically and promoted to the `test` channel.\n1. Interim Companion GitHub releases are deleted automatically when they're no longer needed.\n\n### Other Changes\n\n- Dependency security: The backend's lockfile update process was simplified so that Dependabot can now update lockfiles, too. This removes the need to check out Dependabot PRs locally just to run a lockfile update script.\n", "2.0": "+++\ntitle = \"What's New\"\n+++\n\n## \u26a0\ufe0f Action Required\n\nSambee's GitHub repository was moved to an organization account. This makes it necessary that you update the Docker Compose image URL to `ghcr.io/sambee-app/sambee` in your Docker Compose file (see the [Docker deployment docs](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for details).\n\n## Theme Editor\n\nUI themes are an integral part of an app's visual presentation. As so often, flexibility is key. Some like it dark, others colorful, some require high-contrast, others prefer muted colors.\n\nSambee now has a multi-layer theme system. It differentiates between built-in themes, site-wide themes which only admins can manage, and users' personal themes. Any user can modify existing themes for their own use; admins can also provide themes for other users on the same Sambee server and designate a default theme for new users.\n\nWith Sambee's new theme editor, users can change all theme colors via hex values or the integrated RGBA color picker (which covers transparency in addition to color). Themes can be imported and exported, too.\n\n## File List\n\n### Mouse Selection on Desktop\n\nPrevious versions of Sambee introduced multi-selection for mobile users and keyboard aficionados on desktop. Mouse coverage was lacking. That has been rectified now: Selecting multiple files with a mouse is now straightforward. Click a file or folder icon to select it, then Shift-click another icon to add everything in between without losing your earlier selections. The pane's status bar keeps the count in view.\n\n### New Keyboard Shortcuts\n\n- New tab: \u003ckbd\u003eCtrl+Alt+T\u003c/kbd\u003e opens the current location in a new browser tab.\n- Pane location: \u003ckbd\u003eCtrl+Left\u003c/kbd\u003e sets the left pane to the right pane's location, and \u003ckbd\u003eCtrl+Right\u003c/kbd\u003e sets the right pane to the left pane's location.\n- Item selection: keyboard shortcuts now include \u003ckbd\u003eShift+Home\u003c/kbd\u003e and \u003ckbd\u003eShift+End\u003c/kbd\u003e.\n\n### Other Changes\n\n- Sambee no longer uses \u003ckbd\u003eCtrl+1\u003c/kbd\u003e and \u003ckbd\u003eCtrl+2\u003c/kbd\u003e for pane focus so as not to block these shortcuts for browser tab selection.\n- Native mobile sharing is now available for single or multiple files from the file list.\n- Single-file downloads are now streamed directly without buffering in memory. This speeds up downloads and effectively removes limits imposed by file size.\n\n### Bugfixes\n\n#### File Copy/Move Fixes\n\n- Uploads and copy or move operations no longer interfere with each other's conflict decisions.\n- Moving files between SMB connections no longer leaves the original in place when it should have been deleted.\n- SMB moves now protect the source from concurrent edits and renames, preventing deletion of changes that weren't copied yet.\n- Overwriting an existing SMB file now replaces it atomically instead of failing.\n- Cancelling a move after copying finishes, but before source deletion starts, now correctly reports that both copies were kept.\n- Transfer results now show when a file was copied or replaced, even if removing or checking the original fails.\n- When transferring a folder, a problem with one file no longer hides files already copied, moved, or replaced from the summary.\n- Interrupted SMB moves now release files safely, without leaving them open or interrupting work still in progress.\n- Pressing Enter after a transfer finishes no longer starts the same transfer again.\n- SMB file metadata timezones and ZIP creation now consistently use UTC.\n- SMB connection idle cleanup and failed-request duration logs now use a monotonic clock, so daylight saving time and system clock changes do not affect elapsed-time calculations.\n\n#### SMB Change Monitoring Fixes\n\nFile list:\n\n- File-list monitoring now watches only immediate children, so changes deeper in a folder don't trigger unnecessary refreshes.\n- When changes happen, the file list is now refreshed in the background.\n- File list refreshes are now coalesced and rate-limited.\n\nDirectory cache for instant navigation:\n\n- Quick directory navigation keeps its existing index when a background scan times out or fails.\n- Background scans keep the live directory index when a removal or rename overlaps a read, including when its notification arrives late. This prevents changes from being applied twice when a folder's name is reused.\n- Changing a connection's target or sign-in details no longer reuses directory suggestions from its old configuration.\n- Directory indexing excludes junctions, other reparse descendants, and DFS shares to prevent unsafe traversal.\n- Startup verification and scheduled directory scans now stop cleanly when their cache is removed.\n\n#### Other Fixes\n\n- Invalid file browser URLs no longer break the page or prevent the other pane from loading.\n- Overlapping download requests were allowed.\n- A failed background connection refresh no longer hides a recovered file listing.\n- Renaming a file to a name that differed by case only failed on local drive connections.\n\n## OpenID Connect (OIDC)\n\n### Refresh Token \u0026 `offline_access` Are Now Optional\n\nMany identity providers require the `offline_access` scope to issue refresh tokens, but some (like OneLogin) rejects that scope in the authorization code flow and can issue a refresh token without it when refresh tokens are enabled for the app.\n\nSambee uses a provider refresh token when one is returned, whether or not `offline_access` was requested. If no refresh token is returned, Sambee can continue issuing short-lived API tokens from the browser session for up to 8 hours by default (configurable from 1 to 24 hours). After Sambee's user session expires, the user must sign in through the identity provider again.\n\n### Re-Login Broadcast to Other Open Tabs\n\nWhen an OIDC login is necessary, all Sambee browser tabs switch to the login page. After a successful login in one tab, that tab now broadcasts a login complete hint. When other tabs on the login page receive that hint, they return to their respectice previous URLs.\n\n### Bugfixes\n\n- OIDC login failures after password reset: OIDC login now completes reliably after an administrator resets the account\u2019s password. Sambee ignores responses from the previous browser session while the new login finishes, reloads the user\u2019s themes and settings, and returns to the file browser instead of the login page.\n- Sambee always removed a trailing slash from the issuer URL, which could cause errors with providers like Authentik. Trailing slashes are now left in place.\n\n## Text and Markdown Editors\n\n### Text Viewer and Editor Combined\n\nSambee's text viewer and text editor are now combined into a single component. Text files now open directly in the editor. If write mode cannot be enabled, text editor operates in read-only mode and a notification is shown.\n\nAs part of this change, Sambee got a consistent toast-based notification system for info, warning, and error messages.\n\n### Syntax Highlighting and Rendering Performance Optimization\n\nSambee now uses a consolidated syntax highlighting system throughout all text and Markdown rendering surfaces: text editor, Markdown editor, fenced code blocks in Markdown viewer and Markdown editor. The syntax highlighting system is integrated with the theming system; highlight colors are now part of each theme and can be edited in the new theme editor.\n\nSyntax highlighting is available for a wide range of languages and file types ([docs](../../../user-guide/reference/text-file-support-and-syntax-highlighting/)).\n\nText editor and Markdown editor performance was significantly boosted, especially for long documents. This was achieved through virtualization and viewport rendering.\n\n## Markdown Viewer\n\n### Print and Save as PDF\n\nWhen you print or save as PDF from the browser, the Markdown viewer reformats the full rendered document to fit the page, spanning multiple pages as needed. A new print icon in the top bar makes the new functionality discoverable.\n\n### Other Changes\n\n- Closing the editor by clicking the X now works in the same way as pressing \u003ckbd\u003eEsc\u003c/kbd\u003e: it returns to the viewer. From there, another click returns to the file list.\n- When reloading a browser tab with an editor, Sambee now recovers the file lock. This prevents the error `Unable to enter edit mode. File is locked for editing by \u003cusername\u003e`.\n\n## Quick Bar: Directory Navigation v2\n\nDirectory search and navigation in the quick bar was put on a new foundation:\n\n- Local drives are now indexed, too.\n- The indexing process is now faster and more resilient.\n- The directory index storage was upgraded from JSONL to SQLite databases.\n\n## Miscellaneous\n\n### Native Mobile Sharing\n\nConsolidated the native mobile sharing implementation across the file list and image, PDF, text, and Markdown viewers and editors. When sharing fails, a dialog with details can be invoked to facilitate issue reporting.\n\nText editor and Markdown viewer/editor now have an option to share the current content as text as an alternative to sharing the stored file. This helps circumvent Chrome restrictions that prevent sharing file types such as Markdown.\n\nImage and PDF viewers alway share the displayed content, which may have been normalized for viewing in the browser.\n\n### Full Browser History Navigation\n\nEvery navigation step is now encoded in the URL and recorded in browser history. This enables browser back/forward navigation across the entire Sambee workspace, including the file list, viewers, and editors.\n\n### Local Drive Acess\n\nSambee now checks local-drive access before saying the browser is ready to use Companion. If the check fails, Local Drives settings distinguish between an outdated Companion, an outdated Sambee page, and a pairing that needs to be restored.\n\nWhen Companion rejects a request while browsing a local drive, the file list points to the affected pane and offers a way to reload Sambee or open Local Drives, depending on what went wrong.\n\n### Unencrypted HTTP Support\n\nSambee now deals with unencrypted HTTP explicitly:\n\n- Companion pairing and operations are unavailable.\n- File copying caused a `crypto.randomUUID` error. This has been fixed by implementing a fallback.\n- File uploading would show `outcome uncertain` and not upload files on HTTP/1.1 connections (even over HTTPS). This has been fixed by sending files directly instead of using a streamed request body, so uploads work on HTTP/1.1 while still showing progress.\n- Copying to the clipboard (used in Settings) is now disabled.\n\nHTTP for development on `localhost` is treated as secure by browsers and continues to be supported by Sambee.\n\n### Supported Browser Detection\n\nIf your browser is too old or lacks features Sambee needs, you'll now see a clear message instead of a blank page. The message identifies missing capabilities and links to the browser requirements so you can choose a supported browser.\n\n### Password Login\n\n- When an admin configures a user to require a password change, that change is now enforced upon the next password login.\n- Local usernames are now evaluated case-insensitively.\n- The password field got an option to reveal the password.\n\n### Settings\n\n- User Management: Table column content could overflow into the next row. This was fixes with a comprehensive layout revision.\n\n## Under the Hood\n\n### Security Review\n\nA security review resulted in the following improvements:\n\n- OIDC login now binds the callback and login grant to the browser that started the login flow, preventing a grant from being redeemed in another browser.\n- Only admins can list and download uploaded mobile logs; signed-in users can still upload logs for troubleshooting.\n- Companion requests now use signatures tied to the HTTP method and requested URL, so a signature can't be reused for another request.\n- Mobile log uploads have a size limit, and stored logs are pruned when they exceed the storage budget.\n- HTML, XHTML, and SVG files, including archive members, download instead of running as active content in the viewer.\n\n### Other Changes\n\n- The backend's Python environment was upgraded from 3.13 to 3.14.\n- Fixed the container startup warning: `AuthlibDeprecationWarning: The httpx module is deprecated; please use httpx2 instead.`\n- Reduced the Frontend's JavaScript chunk size.\n\n### Dependency Security\n\n- Updated all dependencies with known issues or vulnerabilities to fixed versions.\n- Pinned all third-party GitHub Actions workflows to commit SHAs.\n- Frontend: removed `patch-package` to get rid of vulnerable transisitve dependency `braces`.\n- Backend: PIP is now upgraded before use and uninstalled from the Docker image afterwards.\n\n### Frontend Type Correctness\n\nType correctness of frontend code and tests is now enforced. As part of this implementation, 1,152 diagnostics across 162 files were fixed: 840 in tests, 311 in application code,\nand one in an imported browser-test helper.\n\n## Internals\n\n- Companion build for Windows: Authenticode signing was removed from PR check builds and only remains on release workflows.\n- GitHub Actions: replaced `pull_request_target` as it will be removed on public repositories by default in November.\n- GitHub Actions: cache retention optimization.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:release-info/system-requirements", "parent_id": "book:release-info", "depth": 1, "kind": "section", "label": "system-requirements", "title": "System Requirements", "path": "release-info/system-requirements", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:release-info/system-requirements/requirements", "parent_id": "section:release-info/system-requirements", "depth": 2, "kind": "page", "label": "requirements", "title": "Requirements", "path": "release-info/system-requirements/requirements", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 4, "diff_removed": 2}}, "content_versions": {"1.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivatives)\n- Mozilla Firefox\n- Apple Safari\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is available for Windows 11 on x64.\n", "2.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivates)\n- Mozilla Firefox\n- Apple Safari\n\nModern browser technologies such as web workers are required. If a browser lacks this or another required capability, Sambee shows a browser compatibility message instead of loading the app.\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is currently available for Windows 11 on x64.\n"}, "page_contents": {"1.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivatives)\n- Mozilla Firefox\n- Apple Safari\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is available for Windows 11 on x64.\n", "2.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivates)\n- Mozilla Firefox\n- Apple Safari\n\nModern browser technologies such as web workers are required. If a browser lacks this or another required capability, Sambee shows a browser compatibility message instead of loading the app.\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is currently available for Windows 11 on x64.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}]}</script>
+  <script id="report-data" type="application/json">{"meta": {"title": "Docs Structure Report", "current_version": "1.0", "report_output": "website-meta/docs-reports/docs-structure-report.html"}, "versions": [{"slug": "0.7", "label": "0.7", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "0.8", "label": "0.8", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "0.9", "label": "0.9", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "1.0", "label": "1.0", "status": "current", "visible": true, "searchable": true, "is_current": true}, {"slug": "2.0", "label": "2.0", "status": "preview", "visible": true, "searchable": false, "is_current": false}], "warnings": [], "rows": [{"id": "book:user-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "user-guide", "title": "User Guide", "path": "user-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 6, "diff_removed": 5}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"User Guide\"\n+++\n\nStart with [What Is Sambee?](./getting-started/what-is-sambee/) for the definition or [What Can You Do With Sambee?](./getting-started/what-can-you-do-with-sambee/) for practical benefits.\n\n- [Find and browse files](./find-and-browse-files/connect-to-an-smb-share/): Open a connection and reach a folder.\n- [Organize files](./organize-and-transfer-files/copy-and-move-files/): Copy or move selected items between locations.\n- [View and edit files](./view-and-edit-files/view-images-and-read-documents/): Preview designs and documents or edit Markdown.\n- [Use desktop apps and local drives](./use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/): Add optional Companion features.\n- [Get help](./troubleshooting/common-user-problems/): Recover from access, editing, or transfer problems.\n- [Check formats](./reference/supported-file-formats/): Find preview support and format limits.\n\nFor deployment and policy, use the [Admin Guide](../admin-guide/). For implementation, use the [Developer Guide](../developer-guide/).\n\n", "0.8": "+++\ntitle = \"User Guide\"\n+++\n\nStart with [What Is Sambee?](./getting-started/what-is-sambee/) for the definition or [What Can You Do With Sambee?](./getting-started/what-can-you-do-with-sambee/) for practical benefits.\n\n- [Find and browse files](./find-and-browse-files/connect-to-an-smb-share/): Open a connection and reach a folder.\n- [Organize files](./organize-and-transfer-files/copy-and-move-files/): Copy or move selected items between locations.\n- [View and edit files](./view-and-edit-files/view-images-and-read-documents/): Preview designs and documents or edit Markdown.\n- [Use desktop apps and local drives](./use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/): Add optional Companion features.\n- [Get help](./troubleshooting/common-user-problems/): Recover from access, editing, or transfer problems.\n- [Check formats](./reference/supported-file-formats/): Find preview support and format limits.\n\nFor deployment and policy, use the [Admin Guide](../admin-guide/). For implementation, use the [Developer Guide](../developer-guide/).\n\n", "0.9": "+++\ntitle = \"User Guide\"\n+++\n\nStart with [What Is Sambee?](./getting-started/what-is-sambee/) for the definition or [What Can You Do With Sambee?](./getting-started/what-can-you-do-with-sambee/) for practical benefits.\n\n- [Find and browse files](./find-and-browse-files/connect-to-an-smb-share/): Open a connection and reach a folder.\n- [Organize files](./organize-and-transfer-files/copy-and-move-files/): Copy or move selected items between locations.\n- [View and edit files](./view-and-edit-files/view-images-and-read-documents/): Preview designs and documents or edit Markdown.\n- [Use desktop apps and local drives](./use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/): Add optional Companion features.\n- [Get help](./troubleshooting/common-user-problems/): Recover from access, editing, or transfer problems.\n- [Check formats](./reference/supported-file-formats/): Find preview support and format limits.\n\nFor deployment and policy, use the [Admin Guide](../admin-guide/). For implementation, use the [Developer Guide](../developer-guide/).\n\n", "1.0": "+++\ntitle = \"User Guide\"\n+++\n\nStart with [What Is Sambee?](./getting-started/what-is-sambee/) for the definition or [What Can You Do With Sambee?](./getting-started/what-can-you-do-with-sambee/) for practical benefits.\n\n- [Find and browse files](./find-and-browse-files/connect-to-an-smb-share/): Open a connection, select items, and find recent locations.\n- [Organize and transfer files](./organize-and-transfer-files/copy-and-move-files/): Copy, move, upload, or download files.\n- [Inspect ZIP archives](./organize-and-transfer-files/work-with-zip-archives/): Preview contents without extracting the whole archive.\n- [View and edit files](./view-and-edit-files/view-images-and-read-documents/): Preview designs, edit text, or update Markdown tables.\n- [Use desktop apps and local drives](./use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/): Add optional Companion features.\n- [Manage your account and preferences](./account-and-preferences/manage-your-account/): Control sessions and personal history.\n- [Get help](./troubleshooting/common-user-problems/): Recover from access, saving, sharing, or transfer problems.\n- [Check formats](./reference/supported-file-formats/): Find preview support and format limits.\n\nFor deployment and policy, use the [Admin Guide](../admin-guide/). For implementation, use the [Developer Guide](../developer-guide/).\n", "2.0": "+++\ntitle = \"User Guide\"\n+++\n\nStart with [What Is Sambee?](./getting-started/what-is-sambee/) for the definition or [What Can You Do With Sambee?](./getting-started/what-can-you-do-with-sambee/) for practical benefits.\n\n- [Find and browse files](./find-and-browse-files/connect-to-an-smb-share/): Open a connection, select items, and find recent locations.\n- [Organize and transfer files](./organize-and-transfer-files/copy-and-move-files/): Copy, move, upload, or download files.\n- [Inspect ZIP archives](./organize-and-transfer-files/work-with-zip-archives/): Preview contents without extracting the whole archive.\n- [View and edit files](./view-and-edit-files/view-images-and-read-documents/): Preview designs, edit text, or update Markdown tables.\n- [Use desktop apps and local drives](./use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/): Add optional Companion features.\n- [Manage your account and preferences](./account-and-preferences/manage-your-account/): Control sessions and personal history.\n- [Get help](./troubleshooting/common-user-problems/): Recover from access, saving, sharing, or transfer problems.\n- [Check formats](./reference/supported-file-formats/): Find preview support and format limits.\n\nFor deployment and policy, use the [Admin Guide](../admin-guide/). For implementation, use the [Developer Guide](../developer-guide/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/getting-started", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "getting-started", "title": "Getting Started", "path": "user-guide/getting-started", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/getting-started/what-is-sambee", "parent_id": "section:user-guide/getting-started", "depth": 2, "kind": "page", "label": "what-is-sambee", "title": "What Is Sambee", "path": "user-guide/getting-started/what-is-sambee", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 1}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "branched", "source_version": "0.8", "diff_added": 27, "diff_removed": 11}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "0.8": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit text and Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\nEdit supported text files directly in storage, or change Markdown tables in their rendered view without aligning markup. See [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/) and [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "0.9": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit text and Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\nEdit supported text files directly in storage, or change Markdown tables in their rendered view without aligning markup. See [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/) and [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "1.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee is a browser-based workspace for files on SMB shares and local drives. Access your data from PCs, phones, and tablets. View images, read PDFs, and edit Markdown right in your browser. On the desktop, open any file in the natively installed apps you already use. Sambee saves your changes back to the original location.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSambee provides access to two types of storage: SMB file shares and your computer's local drives. You can move and copy files between them without restrictions, e.g. from your PC's local drive to a file share, or between different SMB shares.\n\nLocal drive access is requires Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nAny kind of text file can be viewed and edited in the built-in text editor. It provides syntax highlighting for many file types, offers search \u0026 replace, and opens even very large files.\n\n### Desktop App Integration\n\nSambee bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container. See [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/).\n", "2.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee is a browser-based workspace for files on SMB shares and local drives. Access your data from PCs, phones, and tablets. View images, read PDFs, and edit Markdown right in your browser. On the desktop, open any file in the natively installed apps you already use. Sambee saves your changes back to the original location.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSambee provides access to two types of storage: SMB file shares and your computer's local drives. You can move and copy files between them without restrictions, e.g. from your PC's local drive to a file share, or between different SMB shares.\n\nLocal drive access is requires Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nAny kind of text file can be viewed and edited in the built-in text editor. It provides syntax highlighting for many file types, offers search \u0026 replace, and opens even very large files.\n\n### Desktop App Integration\n\nSambee bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container. See [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "0.8": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit text and Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\nEdit supported text files directly in storage, or change Markdown tables in their rendered view without aligning markup. See [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/) and [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "0.9": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a self-hosted, browser-based file manager for files on SMB network shares and local drives. Browse files, view images and PDFs, and edit text and Markdown in your browser. With optional Sambee Companion, access local drives and open network files in installed desktop apps, then upload your changes back to the original share without managing downloaded copies or choosing an upload destination.\n\nSambee can replace traditional tools like Windows File Explorer. Single-pane and dual-pane views bring your existing storage into one workspace.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n### Supports SMB Shares and Local Drives\n\nYour browser accesses SMB shares through the Sambee server. Companion is not required for network shares.\n\nBrowse network files from PCs, phones, and tablets. Local-drive access requires Sambee Companion on a supported desktop computer and browser trust approval; it is not a phone feature.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\nEdit supported text files directly in storage, or change Markdown tables in their rendered view without aligning markup. See [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/) and [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Desktop App Integration\n\nOpen network files in Word, Excel, Photoshop, or another installed app through Sambee Companion. When your work is ready, explicitly upload the changes back to the original share. Closing the app alone does not upload an SMB edit. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "1.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee is a browser-based workspace for files on SMB shares and local drives. Access your data from PCs, phones, and tablets. View images, read PDFs, and edit Markdown right in your browser. On the desktop, open any file in the natively installed apps you already use. Sambee saves your changes back to the original location.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSambee provides access to two types of storage: SMB file shares and your computer's local drives. You can move and copy files between them without restrictions, e.g. from your PC's local drive to a file share, or between different SMB shares.\n\nLocal drive access is requires Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nAny kind of text file can be viewed and edited in the built-in text editor. It provides syntax highlighting for many file types, offers search \u0026 replace, and opens even very large files.\n\n### Desktop App Integration\n\nSambee bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container. See [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/).\n", "2.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee is a browser-based workspace for files on SMB shares and local drives. Access your data from PCs, phones, and tablets. View images, read PDFs, and edit Markdown right in your browser. On the desktop, open any file in the natively installed apps you already use. Sambee saves your changes back to the original location.\n\nSee [What Can You Do With Sambee?](../what-can-you-do-with-sambee/) for examples.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSambee provides access to two types of storage: SMB file shares and your computer's local drives. You can move and copy files between them without restrictions, e.g. from your PC's local drive to a file share, or between different SMB shares.\n\nLocal drive access is requires Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nAny kind of text file can be viewed and edited in the built-in text editor. It provides syntax highlighting for many file types, offers search \u0026 replace, and opens even very large files.\n\n### Desktop App Integration\n\nSambee bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container. See [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/getting-started/what-can-you-do-with-sambee", "parent_id": "section:user-guide/getting-started", "depth": 2, "kind": "page", "label": "what-can-you-do-with-sambee", "title": "What Can You Do With Sambee", "path": "user-guide/getting-started/what-can-you-do-with-sambee", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 1}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "branched", "source_version": "0.8", "diff_added": 13, "diff_removed": 13}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Review a design from your phone or open a network file in your favorite desktop app. Sambee brings these workflows to the storage you already use.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "0.8": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Preview design files from your phone, change a Markdown table without editing its markup, or open a network file in your favorite desktop app.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Change Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in its rendered table view, instead of aligning pipes and rows in source text. Your document stays a Markdown file in its existing storage. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "0.9": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Preview design files from your phone, change a Markdown table without editing its markup, or open a network file in your favorite desktop app.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Change Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in its rendered table view, instead of aligning pipes and rows in source text. Your document stays a Markdown file in its existing storage. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "1.0": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nWork more easily with your files on the storage you already have. Preview image files on your phone, browse a ZIP without unpacking it, edit a Markdown table effortlessly, or open a network file in your favorite desktop app. Sambee brings all of this to the storage you already have.\n\n## Give Your Existing Storage a Modern Workspace\n\nYour project files can stay on your NAS or Windows file server. There's no cloud to migrate to and no synced copy to maintain. Just [connect to an SMB share](../../find-and-browse-files/connect-to-an-smb-share/) and start working. Add Companion to [bring local drives into the same workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files on Your Phone\n\nCheck a Photoshop design or a HEIC photo straight from a network share. You don't need the desktop app, and you don't need to download the file first. Swipe through large image collections, including formats your browser can't display natively. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/), [Supported File Formats](../../reference/supported-file-formats/), and [Mobile Navigation](../../find-and-browse-files/mobile-navigation/).\n\n## Look Inside a ZIP Without Unpacking It\n\nOpen a ZIP like a folder and view the images and documents inside. Find what you need without extracting the whole archive, then download or extract only the files you want. This works even with read-only access to an SMB share, and you don't need Companion. See [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/).\n\n## Edit Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in a rendered table view instead of lining up pipes in source text. The document stays a plain Markdown file, right where it was. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a folder name and jump straight to it. [Get back to recent files and locations](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) in a few keystrokes. On desktop, use [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders side by side or [move files between them](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Edit in Your Desktop Apps, Save Back to the Share\n\nOpen network files in Word, Photoshop, LibreOffice, or any other installed app. Sambee Companion handles the handoff and uploads your changes back to the original location, so you don't have to juggle downloads and uploads yourself. See [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "2.0": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nWork more easily with your files on the storage you already have. Preview image files on your phone, browse a ZIP without unpacking it, edit a Markdown table effortlessly, or open a network file in your favorite desktop app. Sambee brings all of this to the storage you already have.\n\n## Give Your Existing Storage a Modern Workspace\n\nYour project files can stay on your NAS or Windows file server. There's no cloud to migrate to and no synced copy to maintain. Just [connect to an SMB share](../../find-and-browse-files/connect-to-an-smb-share/) and start working. Add Companion to [bring local drives into the same workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files on Your Phone\n\nCheck a Photoshop design or a HEIC photo straight from a network share. You don't need the desktop app, and you don't need to download the file first. Swipe through large image collections, including formats your browser can't display natively. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/), [Supported File Formats](../../reference/supported-file-formats/), and [Mobile Navigation](../../find-and-browse-files/mobile-navigation/).\n\n## Look Inside a ZIP Without Unpacking It\n\nOpen a ZIP like a folder and view the images and documents inside. Find what you need without extracting the whole archive, then download or extract only the files you want. This works even with read-only access to an SMB share, and you don't need Companion. See [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/).\n\n## Edit Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in a rendered table view instead of lining up pipes in source text. The document stays a plain Markdown file, right where it was. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a folder name and jump straight to it. [Get back to recent files and locations](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) in a few keystrokes. On desktop, use [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders side by side or [move files between them](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Edit in Your Desktop Apps, Save Back to the Share\n\nOpen network files in Word, Photoshop, LibreOffice, or any other installed app. Sambee Companion handles the handoff and uploads your changes back to the original location, so you don't have to juggle downloads and uploads yourself. See [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Review a design from your phone or open a network file in your favorite desktop app. Sambee brings these workflows to the storage you already use.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "0.8": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Preview design files from your phone, change a Markdown table without editing its markup, or open a network file in your favorite desktop app.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Change Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in its rendered table view, instead of aligning pipes and rows in source text. Your document stays a Markdown file in its existing storage. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "0.9": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nKeep your files where they are and do more with them. Preview design files from your phone, change a Markdown table without editing its markup, or open a network file in your favorite desktop app.\n\n## Give Your Existing Storage a Modern Workspace\n\nKeep project files on your NAS or Windows file server, without migrating to a cloud library. [Open an SMB connection](../../find-and-browse-files/connect-to-an-smb-share/). With Companion, [bring local drives into the workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files from Your Phone\n\nCheck a Photoshop design or HEIC photo on a network share without installing its desktop app or downloading it first. Browse a large image collection, including formats your browser cannot display on its own. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/) and [Supported File Formats](../../reference/supported-file-formats/).\n\n## Change Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in its rendered table view, instead of aligning pipes and rows in source text. Your document stays a Markdown file in its existing storage. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a directory name and jump to the matching folder. Use [smart navigation](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) to reach a project quickly, and [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders on desktop.\n\n## Edit in Your Desktop Apps. Return Changes to the Original Share.\n\nWork on network files in Word, Photoshop, LibreOffice, or another installed app. Sambee Companion handles the file handoff and uploads your finished edits back to their source, so you do not have to manage a separate download-and-upload workflow. See [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Start with a Preview\n\n[Preview a design or photo](../../view-and-edit-files/view-images-and-read-documents/), even with read-only access and without Companion. If no connection is available, see [connection guidance](../../find-and-browse-files/connect-to-an-smb-share/).\n", "1.0": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nWork more easily with your files on the storage you already have. Preview image files on your phone, browse a ZIP without unpacking it, edit a Markdown table effortlessly, or open a network file in your favorite desktop app. Sambee brings all of this to the storage you already have.\n\n## Give Your Existing Storage a Modern Workspace\n\nYour project files can stay on your NAS or Windows file server. There's no cloud to migrate to and no synced copy to maintain. Just [connect to an SMB share](../../find-and-browse-files/connect-to-an-smb-share/) and start working. Add Companion to [bring local drives into the same workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files on Your Phone\n\nCheck a Photoshop design or a HEIC photo straight from a network share. You don't need the desktop app, and you don't need to download the file first. Swipe through large image collections, including formats your browser can't display natively. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/), [Supported File Formats](../../reference/supported-file-formats/), and [Mobile Navigation](../../find-and-browse-files/mobile-navigation/).\n\n## Look Inside a ZIP Without Unpacking It\n\nOpen a ZIP like a folder and view the images and documents inside. Find what you need without extracting the whole archive, then download or extract only the files you want. This works even with read-only access to an SMB share, and you don't need Companion. See [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/).\n\n## Edit Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in a rendered table view instead of lining up pipes in source text. The document stays a plain Markdown file, right where it was. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a folder name and jump straight to it. [Get back to recent files and locations](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) in a few keystrokes. On desktop, use [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders side by side or [move files between them](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Edit in Your Desktop Apps, Save Back to the Share\n\nOpen network files in Word, Photoshop, LibreOffice, or any other installed app. Sambee Companion handles the handoff and uploads your changes back to the original location, so you don't have to juggle downloads and uploads yourself. See [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n", "2.0": "+++\ntitle = \"What Can You Do With Sambee?\"\n+++\n\nWork more easily with your files on the storage you already have. Preview image files on your phone, browse a ZIP without unpacking it, edit a Markdown table effortlessly, or open a network file in your favorite desktop app. Sambee brings all of this to the storage you already have.\n\n## Give Your Existing Storage a Modern Workspace\n\nYour project files can stay on your NAS or Windows file server. There's no cloud to migrate to and no synced copy to maintain. Just [connect to an SMB share](../../find-and-browse-files/connect-to-an-smb-share/) and start working. Add Companion to [bring local drives into the same workspace](../../use-local-drives-and-desktop-apps/access-local-drives/) and [copy files between drives and shares](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Preview Design Files on Your Phone\n\nCheck a Photoshop design or a HEIC photo straight from a network share. You don't need the desktop app, and you don't need to download the file first. Swipe through large image collections, including formats your browser can't display natively. See [View Images and Read Documents](../../view-and-edit-files/view-images-and-read-documents/), [Supported File Formats](../../reference/supported-file-formats/), and [Mobile Navigation](../../find-and-browse-files/mobile-navigation/).\n\n## Look Inside a ZIP Without Unpacking It\n\nOpen a ZIP like a folder and view the images and documents inside. Find what you need without extracting the whole archive, then download or extract only the files you want. This works even with read-only access to an SMB share, and you don't need Companion. See [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/).\n\n## Edit Markdown Tables Without Fighting the Markup\n\nUpdate a project checklist or comparison table in a rendered table view instead of lining up pipes in source text. The document stays a plain Markdown file, right where it was. See [Edit Markdown](../../view-and-edit-files/edit-markdown/).\n\n## Stop Digging Through Folder Trees\n\nType part of a folder name and jump straight to it. [Get back to recent files and locations](../../find-and-browse-files/smart-navigation-and-the-quick-bar/) in a few keystrokes. On desktop, use [two panes](../../find-and-browse-files/dual-pane-mode/) to compare folders side by side or [move files between them](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Edit in Your Desktop Apps, Save Back to the Share\n\nOpen network files in Word, Photoshop, LibreOffice, or any other installed app. Sambee Companion handles the handoff and uploads your changes back to the original location, so you don't have to juggle downloads and uploads yourself. See [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/find-and-browse-files", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "find-and-browse-files", "title": "Find and Browse Files", "path": "user-guide/find-and-browse-files", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/connect-to-an-smb-share", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "connect-to-an-smb-share", "title": "Connect To An Smb Share", "path": "user-guide/find-and-browse-files/connect-to-an-smb-share", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "0.8": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "0.9": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "1.0": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "2.0": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "0.8": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "0.9": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "1.0": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n", "2.0": "+++\ntitle = \"Open Connections and Browse Folders\"\n+++\n\nChoose an available SMB connection from the **Connection List** to open its files. Your browser accesses the share through the Sambee server; Companion is not required.\n\nIf no connection is available, add one if your account permits it or ask your administrator for access. Shared visibility does not grant permission to read or change the files. A read-only connection permits previews but not edits or transfers into it.\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/). To reach a deep folder quickly, use [directory navigation](../smart-navigation-and-the-quick-bar/).\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/select-files-and-folders", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "select-files-and-folders", "title": "Select Files And Folders", "path": "user-guide/find-and-browse-files/select-files-and-folders", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 12, "diff_removed": 2}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 9, "diff_removed": 5}}, "content_versions": {"0.7": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "0.8": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "0.9": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "1.0": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Each pane has its own selection; bulk actions use the active pane.\n\n## Touch Selection\n\nOn phones, select an item from **More actions** or touch and hold its row. Tap more rows to change the selection, then use the pane's bottom selection controls.\n\nLarger touch devices can use the same behavior without switching to the phone layout. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#file-selection).\n\n## Keyboard Selection\n\n**Space** or **Insert** toggles selection on the focused row and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) rather than a second shortcut list here.\n\nContinue with [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) or [Download and Upload Files](../../organize-and-transfer-files/download-and-upload-files/).\n", "2.0": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Each pane keeps its selection when you switch panes; bulk actions use the active pane.\n\n## Desktop Mouse Selection\n\nWith touch selection off, click the name to open an item or its icon to select it. After the first selection, icons become selection controls. **Shift**-click an icon to add a range without losing earlier selections. Mouse and keyboard selection share the range anchor.\n\nClicking outside the icon or in empty list space clears selection **without opening the item**; click again to open it. **Escape** also clears selection. Sorting or starting File Search clears the active pane's selection.\n\n## Touch Selection\n\nOn phones, select from **More actions** or touch and hold a row. Tap additional rows to change the selection, then use the pane's bottom selection controls. Larger touch devices can use this behavior too; see [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#file-selection).\n\n## Keyboard Selection\n\nSee [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for the selection commands.\n\nContinue with [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) or [Download and Upload Files](../../organize-and-transfer-files/download-and-upload-files/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "0.8": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "0.9": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Copy and move commands use the selected items in the active pane, not the other pane's selection.\n\nWith keyboard focus on a row, **Space** or **Insert** toggles its selection and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for range and whole-list selection. Use [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers.\n", "1.0": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Each pane has its own selection; bulk actions use the active pane.\n\n## Touch Selection\n\nOn phones, select an item from **More actions** or touch and hold its row. Tap more rows to change the selection, then use the pane's bottom selection controls.\n\nLarger touch devices can use the same behavior without switching to the phone layout. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#file-selection).\n\n## Keyboard Selection\n\n**Space** or **Insert** toggles selection on the focused row and moves down. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) rather than a second shortcut list here.\n\nContinue with [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) or [Download and Upload Files](../../organize-and-transfer-files/download-and-upload-files/).\n", "2.0": "+++\ntitle = \"Select Files and Folders\"\n+++\n\nOpening a file is different from selecting it for a bulk action. A focused row alone is not a selection. Each pane keeps its selection when you switch panes; bulk actions use the active pane.\n\n## Desktop Mouse Selection\n\nWith touch selection off, click the name to open an item or its icon to select it. After the first selection, icons become selection controls. **Shift**-click an icon to add a range without losing earlier selections. Mouse and keyboard selection share the range anchor.\n\nClicking outside the icon or in empty list space clears selection **without opening the item**; click again to open it. **Escape** also clears selection. Sorting or starting File Search clears the active pane's selection.\n\n## Touch Selection\n\nOn phones, select from **More actions** or touch and hold a row. Tap additional rows to change the selection, then use the pane's bottom selection controls. Larger touch devices can use this behavior too; see [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#file-selection).\n\n## Keyboard Selection\n\nSee [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/#selection-and-dual-pane-workflows) for the selection commands.\n\nContinue with [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) or [Download and Upload Files](../../organize-and-transfer-files/download-and-upload-files/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "smart-navigation-and-the-quick-bar", "title": "Smart Navigation And The Quick Bar", "path": "user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 44, "diff_removed": 8}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 20, "diff_removed": 12}}, "content_versions": {"0.7": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "0.8": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "0.9": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "1.0": "+++\ntitle = \"Find Files and Return to Recent Locations\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nHistory is private to your account. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#clear-personal-history) to clear it.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search searches names in the active directory's loaded files and your recent-file history. It is not a global file index and does not search contents. A file in both groups appears once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\n## Locate and Run Any Command\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/).\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n", "2.0": "+++\ntitle = \"Find Files and Return to Recent Locations\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\nPress \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to search directory paths across the current connection and your recent locations. For example, `annual reports` finds paths containing either term, with matches for both terms ranked first.\n\nResults can be incomplete while Sambee scans folders. During a scan, the status shows directories found or directories checked. An interrupted scan keeps committed progress for its next attempt. If a folder is missing from search, browse to it directly.\n\nStatus messages identify the connection. **Not all directories could be indexed** means some folders were skipped; available results remain usable. When a message has additional details, it appears as a link that you can click or tap. The status dialog lists affected locations and reasons, or specific request-error details. These links are outside keyboard navigation so focus stays in the quick bar.\n\nDirectory details are a limited sample from the current running source, not a full error history. They can be unavailable after a restart until another scan collects them. Check the listed folder permissions or names when applicable. Some locations are deliberately excluded for safe traversal and do not require a repair.\n\nIf directory search is temporarily unavailable, the quick bar keeps recent history and results already shown for the same search. It checks for recovery while open. A paused status does not mean that a scan is still running. Restore source access if the message reports a connection problem; direct browsing can remain available while search recovers.\n\nDirectory indexes are reused after a restart. Results can remain unverified while background checks run. Missing removable media keeps its saved index; insert or mount the volume again to resume search. SMB search includes ordinary folders inside the configured share and folder, including server-mounted storage. Local search does not cross into other mounts. Redirects and reparse points are excluded.\n\n### Recent Directory History\n\nWith an empty search box, Recent directories shows your saved locations across connections. These remain available while directory search loads.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nHistory is private to your account. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#clear-personal-history) to clear it.\n\n### Missing or Inaccessible Folders\n\nIf a folder cannot be opened, Sambee keeps your current location. If the open folder or a directly linked folder no longer exists, Sambee tries an accessible parent instead. Follow the displayed recovery action if access fails.\n\nConfirmed missing folders are removed from recent history. Temporary connection or permission problems keep the history entry for another attempt.\n\n## Find Files with File Search\n\nPress \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus to search loaded filenames in the active directory and your recent-file history. It does not search all files or file contents. Files matching more search terms rank first.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nConfirmed missing files are removed from recent history. Temporary access problems keep the entry for another attempt. If a native application does not open the file, check Companion or the application for an error.\n\n## Locate and Run Any Command\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/).\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "0.8": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "0.9": "+++\ntitle = \"Find Files and Jump to Folders\"\n+++\n\nThe **Quick Bar** finds directories and commands without clicking through menus.\n\n## Jump to a Directory\n\nPress **Ctrl + K**, then enter part of a directory name. Matches come from the current connection. Choose a result to open that directory.\n\n## Filter the Current Folder\n\n**Ctrl + Alt + F** filters the active folder by file or directory name. It is not a global file index and does not search file contents.\n\n## Find a Command\n\nUse **Ctrl + P** or **F1** to search commands by name. See [Keyboard Navigation and Shortcuts](../keyboard-navigation-and-shortcuts/) for keyboard help, or [Select Files and Folders](../select-files-and-folders/) for bulk actions.\n", "1.0": "+++\ntitle = \"Find Files and Return to Recent Locations\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nHistory is private to your account. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#clear-personal-history) to clear it.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search searches names in the active directory's loaded files and your recent-file history. It is not a global file index and does not search contents. A file in both groups appears once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\n## Locate and Run Any Command\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/).\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n", "2.0": "+++\ntitle = \"Find Files and Return to Recent Locations\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\nPress \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to search directory paths across the current connection and your recent locations. For example, `annual reports` finds paths containing either term, with matches for both terms ranked first.\n\nResults can be incomplete while Sambee scans folders. During a scan, the status shows directories found or directories checked. An interrupted scan keeps committed progress for its next attempt. If a folder is missing from search, browse to it directly.\n\nStatus messages identify the connection. **Not all directories could be indexed** means some folders were skipped; available results remain usable. When a message has additional details, it appears as a link that you can click or tap. The status dialog lists affected locations and reasons, or specific request-error details. These links are outside keyboard navigation so focus stays in the quick bar.\n\nDirectory details are a limited sample from the current running source, not a full error history. They can be unavailable after a restart until another scan collects them. Check the listed folder permissions or names when applicable. Some locations are deliberately excluded for safe traversal and do not require a repair.\n\nIf directory search is temporarily unavailable, the quick bar keeps recent history and results already shown for the same search. It checks for recovery while open. A paused status does not mean that a scan is still running. Restore source access if the message reports a connection problem; direct browsing can remain available while search recovers.\n\nDirectory indexes are reused after a restart. Results can remain unverified while background checks run. Missing removable media keeps its saved index; insert or mount the volume again to resume search. SMB search includes ordinary folders inside the configured share and folder, including server-mounted storage. Local search does not cross into other mounts. Redirects and reparse points are excluded.\n\n### Recent Directory History\n\nWith an empty search box, Recent directories shows your saved locations across connections. These remain available while directory search loads.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nHistory is private to your account. See [File Browser Preferences](../../account-and-preferences/file-browser-preferences/#clear-personal-history) to clear it.\n\n### Missing or Inaccessible Folders\n\nIf a folder cannot be opened, Sambee keeps your current location. If the open folder or a directly linked folder no longer exists, Sambee tries an accessible parent instead. Follow the displayed recovery action if access fails.\n\nConfirmed missing folders are removed from recent history. Temporary connection or permission problems keep the history entry for another attempt.\n\n## Find Files with File Search\n\nPress \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus to search loaded filenames in the active directory and your recent-file history. It does not search all files or file contents. Files matching more search terms rank first.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nConfirmed missing files are removed from recent history. Temporary access problems keep the entry for another attempt. If a native application does not open the file, check Companion or the application for an error.\n\n## Locate and Run Any Command\n\nFor bulk actions, see [Select Files and Folders](../select-files-and-folders/).\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/mobile-navigation", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "mobile-navigation", "title": "Mobile Navigation", "path": "user-guide/find-and-browse-files/mobile-navigation", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "0.8": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "0.9": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "1.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "2.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor sharing stored files, viewer copies, and unsaved text, see [Share Files on Phones and Tablets](../../organize-and-transfer-files/share-files-on-phones-and-tablets/).\n\nWith unsaved edits, navigation offers **Save**, **Discard**, or **Cancel**. Cancel keeps the draft and current location; a failed Save keeps the editor open. Browser history does not undo saved changes or restore discarded edits. See [Recover Unsaved Edits](../../view-and-edit-files/recover-unsaved-edits/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "0.8": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "0.9": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "1.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor file sharing and access requirements for links, see [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n", "2.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\nFor sharing stored files, viewer copies, and unsaved text, see [Share Files on Phones and Tablets](../../organize-and-transfer-files/share-files-on-phones-and-tablets/).\n\nWith unsaved edits, navigation offers **Save**, **Discard**, or **Cancel**. Cancel keeps the draft and current location; a failed Save keeps the editor open. Browser history does not undo saved changes or restore discarded edits. See [Recover Unsaved Edits](../../view-and-edit-files/recover-unsaved-edits/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/dual-pane-mode", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "dual-pane-mode", "title": "Dual Pane Mode", "path": "user-guide/find-and-browse-files/dual-pane-mode", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 1, "diff_removed": 1}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 13, "diff_removed": 4}}, "content_versions": {"0.7": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.8": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.9": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "1.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers, or [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/) for extraction.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "2.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nUse \u003ckbd\u003eTab\u003c/kbd\u003e to move focus between the panes. To focus a specific pane, use **Focus Left Pane** or **Focus Right Pane** in command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e). **Focus Right Pane** also opens dual-pane mode if only one pane is visible.\n\n## Match Pane Locations\n\nUse these commands to show the same connection and directory in both panes:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eLeft\u003c/kbd\u003e to set the left pane to the right pane's location.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eRight\u003c/kbd\u003e to set the right pane to the left pane's location.\n\nThe direction selects the pane to change, regardless of which pane is active. The active pane and keyboard focus stay unchanged. These commands copy only the location, including archive subdirectories. They don't copy or move files, selections, or pane preferences. Both locations must finish loading first. If they already match, nothing changes. Use browser Back to restore the previous locations.\n\nTo open the active pane's location separately, press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e. The new tab contains one pane. The original tab stays unchanged.\n\nAll three commands are also available through command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e).\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers, or [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/) for extraction.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.8": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.9": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfer instructions.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "1.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers, or [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/) for extraction.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "2.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nUse \u003ckbd\u003eTab\u003c/kbd\u003e to move focus between the panes. To focus a specific pane, use **Focus Left Pane** or **Focus Right Pane** in command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e). **Focus Right Pane** also opens dual-pane mode if only one pane is visible.\n\n## Match Pane Locations\n\nUse these commands to show the same connection and directory in both panes:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eLeft\u003c/kbd\u003e to set the left pane to the right pane's location.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eRight\u003c/kbd\u003e to set the right pane to the left pane's location.\n\nThe direction selects the pane to change, regardless of which pane is active. The active pane and keyboard focus stay unchanged. These commands copy only the location, including archive subdirectories. They don't copy or move files, selections, or pane preferences. Both locations must finish loading first. If they already match, nothing changes. Use browser Back to restore the previous locations.\n\nTo open the active pane's location separately, press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e. The new tab contains one pane. The original tab stays unchanged.\n\nAll three commands are also available through command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e).\n\n## Requirements\n\nUse [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/) for transfers, or [Work with ZIP Archives](../../organize-and-transfer-files/work-with-zip-archives/) for extraction.\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/find-and-browse-files/keyboard-navigation-and-shortcuts", "parent_id": "section:user-guide/find-and-browse-files", "depth": 2, "kind": "page", "label": "keyboard-navigation-and-shortcuts", "title": "Keyboard Navigation And Shortcuts", "path": "user-guide/find-and-browse-files/keyboard-navigation-and-shortcuts", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 37, "diff_removed": 13}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 8, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.8": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.9": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "1.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee. Press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e for a searchable list of shortcuts in the app.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "2.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee. Press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e for a searchable list of shortcuts in the app.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Open the active pane's current location in a new browser tab |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eLeft\u003c/kbd\u003e | Set the left pane to the right pane's connection and directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eRight\u003c/kbd\u003e | Set the right pane to the left pane's connection and directory |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\nThe location commands are also available through command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e). They require loaded pane locations and are unavailable in viewers, dialogs, and text inputs. Opening a new tab copies only the location, including an archive subdirectory, not selection, scroll position, or the second pane. Browser settings control where the page opens. If your operating system uses \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e for a terminal, use command search instead.\n\nMatching pane locations doesn't move files or change the active pane. Use browser Back to restore the previous locations. If both locations already match, the command makes no change.\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Retry editing when the file is read-only because its lock or write access is temporarily unavailable; disabled while a retry is pending |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.8": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.9": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "1.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee. Press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e for a searchable list of shortcuts in the app.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "2.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee. Press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e for a searchable list of shortcuts in the app.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Open the active pane's current location in a new browser tab |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eLeft\u003c/kbd\u003e | Set the left pane to the right pane's connection and directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eRight\u003c/kbd\u003e | Set the right pane to the left pane's connection and directory |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\nThe location commands are also available through command search (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e). They require loaded pane locations and are unavailable in viewers, dialogs, and text inputs. Opening a new tab copies only the location, including an archive subdirectory, not selection, scroll position, or the second pane. Browser settings control where the page opens. If your operating system uses \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e for a terminal, use command search instead.\n\nMatching pane locations doesn't move files or change the active pane. Use browser Back to restore the previous locations. If both locations already match, the command makes no change.\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Retry editing when the file is read-only because its lock or write access is temporarily unavailable; disabled while a retry is pending |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/organize-and-transfer-files", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "organize-and-transfer-files", "title": "Organize and Transfer Files", "path": "user-guide/organize-and-transfer-files", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/organize-and-transfer-files/copy-and-move-files", "parent_id": "section:user-guide/organize-and-transfer-files", "depth": 2, "kind": "page", "label": "copy-and-move-files", "title": "Copy And Move Files", "path": "user-guide/organize-and-transfer-files/copy-and-move-files", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 5}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 14, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "0.8": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "0.9": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "1.0": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop. Select source files or folders in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move. Transfers work between SMB connections, local drives, and shares and drives. The destination must be writable; local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/). Sambee completes the destination copy before removing the source during a move.\n\nIf a destination item exists, use **Target already exists** to skip it or choose a different name. To extract ZIP members instead, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Partial Moves and Cancellation\n\nIf Sambee creates the destination but cannot remove the original, it reports a partial move and keeps the original. Cancellation or failure does not undo earlier completed items. Review both locations before retrying or deleting a retained source. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "2.0": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop. Select source files or folders in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move. Transfers work between SMB connections, local drives, and shares and drives. The destination must be writable; local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/). Sambee completes the destination copy before removing the source during a move. For ZIP members, use [extraction](../work-with-zip-archives/#extract-selected-members); members cannot be moved.\n\n## Existing Destination Items\n\nIn **Target already exists**, skip, overwrite, overwrite only if the source is newer, or choose another name. You can apply a choice to remaining conflicts. Same-name directories are merged without deleting destination-only entries. A file cannot replace a directory or the reverse.\n\n## Partial Moves and Cancellation\n\nFor moves between SMB connections, the destination file is complete before source deletion. An authorized overwrite does not first delete the visible destination. Another writer can prevent a move from starting.\n\n- Cancellation before destination publication leaves both locations unchanged for that file.\n- Cancellation after publication but before source deletion retains the destination and reports the retained source.\n- Rejected source deletion retains the confirmed destination and reports the retained source.\n- If deletion or final close cannot be confirmed, Sambee reports uncertainty. Cancellation after deletion starts does not guarantee that the source remains.\n\nDirectories can be partially moved. Earlier completed files and replacements are not rolled back. An uncertain item stops the remaining batch; a retained-source warning can allow later items to continue. Each selected directory uses the destination parent captured when the confirmation opened.\n\nInspect both locations before retrying. Do not assume an uncertain source was retained. The completed dialog offers **Close**, not a repeat of the batch. If source validation fails after a copy was published, the destination remains and the failure is reported. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "0.8": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "0.9": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop to transfer files between folders. Select the source items in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move the selected items. Copying works between SMB connections, local drives, and shares and drives. Local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/), and the destination must be writable.\n\n## Retained Sources and Partial Results\n\nFor a move across storage boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete it. Check both locations before deleting a retained source yourself.\n\nA failed or cancelled batch can leave completed files in the destination. Do not assume that the whole operation was undone. Inspect source and destination before retrying. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "1.0": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop. Select source files or folders in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move. Transfers work between SMB connections, local drives, and shares and drives. The destination must be writable; local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/). Sambee completes the destination copy before removing the source during a move.\n\nIf a destination item exists, use **Target already exists** to skip it or choose a different name. To extract ZIP members instead, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Partial Moves and Cancellation\n\nIf Sambee creates the destination but cannot remove the original, it reports a partial move and keeps the original. Cancellation or failure does not undo earlier completed items. Review both locations before retrying or deleting a retained source. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n", "2.0": "+++\ntitle = \"Copy and Move Files\"\n+++\n\nUse [dual-pane mode](../../find-and-browse-files/dual-pane-mode/) on desktop. Select source files or folders in the active pane; the inactive pane is the destination. A focused row alone is not a selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\nPress **F5** to copy or **F6** to move. Transfers work between SMB connections, local drives, and shares and drives. The destination must be writable; local drives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/). Sambee completes the destination copy before removing the source during a move. For ZIP members, use [extraction](../work-with-zip-archives/#extract-selected-members); members cannot be moved.\n\n## Existing Destination Items\n\nIn **Target already exists**, skip, overwrite, overwrite only if the source is newer, or choose another name. You can apply a choice to remaining conflicts. Same-name directories are merged without deleting destination-only entries. A file cannot replace a directory or the reverse.\n\n## Partial Moves and Cancellation\n\nFor moves between SMB connections, the destination file is complete before source deletion. An authorized overwrite does not first delete the visible destination. Another writer can prevent a move from starting.\n\n- Cancellation before destination publication leaves both locations unchanged for that file.\n- Cancellation after publication but before source deletion retains the destination and reports the retained source.\n- Rejected source deletion retains the confirmed destination and reports the retained source.\n- If deletion or final close cannot be confirmed, Sambee reports uncertainty. Cancellation after deletion starts does not guarantee that the source remains.\n\nDirectories can be partially moved. Earlier completed files and replacements are not rolled back. An uncertain item stops the remaining batch; a retained-source warning can allow later items to continue. Each selected directory uses the destination parent captured when the confirmation opened.\n\nInspect both locations before retrying. Do not assume an uncertain source was retained. The completed dialog offers **Close**, not a repeat of the batch. If source validation fails after a copy was published, the destination remains and the failure is reported. See [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/organize-and-transfer-files/share-files-and-links", "parent_id": "section:user-guide/organize-and-transfer-files", "depth": 2, "kind": "page", "label": "share-files-and-links", "title": "Share Files And Links", "path": "user-guide/organize-and-transfer-files/share-files-and-links", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "missing"}}, "content_versions": {"0.7": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "0.8": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "0.9": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "1.0": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "0.8": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "0.9": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n", "1.0": "+++\ntitle = \"Share Folder Links and Mobile Files\"\n+++\n\n## Share a Folder Location\n\nA link to a Sambee folder points to its location; it does not grant access. Recipients need access to the Sambee site, connection, and folder. Local-drive links also require the recipient's supported desktop Companion path with that drive available.\n\n## Share a File from a Phone or Tablet\n\nSambee's file-sharing action is available only on mobile platforms: phones and tablets. It is not available on desktop platforms. Support also depends on your mobile browser and device.\n\nIf sharing is unavailable, use **Download** and send the file through another app on your device. Downloading or sharing a copy does not change the original file's access permissions.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/organize-and-transfer-files/download-and-upload-files", "parent_id": "section:user-guide/organize-and-transfer-files", "depth": 2, "kind": "page", "label": "download-and-upload-files", "title": "Download And Upload Files", "path": "user-guide/organize-and-transfer-files/download-and-upload-files", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"1.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nFor persistent archive creation and extraction, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If Sambee cannot confirm whether a folder upload succeeded, Sambee stops the remaining transfers; inspect the destination before trying again.\n\nSee [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer) before retrying a partial or uncertain upload.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n", "2.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nFor persistent archive creation and extraction, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If Sambee cannot confirm whether a folder upload succeeded, Sambee stops the remaining transfers; inspect the destination before trying again.\n\nSee [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer) before retrying a partial or uncertain upload.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n"}, "page_contents": {"1.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nFor persistent archive creation and extraction, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If Sambee cannot confirm whether a folder upload succeeded, Sambee stops the remaining transfers; inspect the destination before trying again.\n\nSee [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer) before retrying a partial or uncertain upload.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n", "2.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nFor persistent archive creation and extraction, see [Work with ZIP Archives](../work-with-zip-archives/).\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If Sambee cannot confirm whether a folder upload succeeded, Sambee stops the remaining transfers; inspect the destination before trying again.\n\nSee [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer) before retrying a partial or uncertain upload.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/organize-and-transfer-files/work-with-zip-archives", "parent_id": "section:user-guide/organize-and-transfer-files", "depth": 2, "kind": "page", "label": "work-with-zip-archives", "title": "Work With Zip Archives", "path": "user-guide/organize-and-transfer-files/work-with-zip-archives", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"1.0": "+++\ntitle = \"Work with ZIP Archives\"\n+++\n\n## Look Inside a ZIP\n\nOpen a ZIP as a virtual folder on an SMB share or paired local drive. Browse its directories and preview supported files inside it without extracting the whole archive. Read-only access is enough for inspection. Local archives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/); SMB archives do not.\n\nSambee cannot preview or extract encrypted members or members with unsupported compression. These members appear in lighter text; hover over a row to see its reason. Use another archive tool, with the password for encrypted members, to access them.\n\n## Download Selected Contents\n\nSelect archive members or folders and choose **Download** to get a new ZIP containing those items. A selected folder includes its contents. This does not create an archive in storage. See [download limits](../download-and-upload-files/#download-limits).\n\n## Extract Selected Members\n\nOn desktop, open the ZIP in the active pane and a writable physical folder in the other pane. Select members and press **F5** to extract them there. Selected directories include all their contents and empty directories. Archive members cannot be moved; **F6** is unavailable and does not modify the ZIP.\n\nExtraction continues for readable members inside a selected folder. The completion notice reports skipped members and gives separate counts for encryption and unsupported compression.\n\nExtraction can leave partial results after failure or cancellation. Inspect the destination before retrying; see [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n\n## Create an Archive in Storage\n\nUnlike a generated download, **Create archive** writes a persistent ZIP into the destination folder. For files selected inside a ZIP, open a writable physical folder on the **same SMB connection** in the other pane, then choose **Create archive**. Creating an archive from ZIP members is not available for local-drive or mixed-connection destinations.\n\nFor ordinary stored files or folders, select the source items and choose **Create archive** with a writable physical destination. Source items must belong to one connection. The action is unavailable for unsupported source or destination combinations; a ZIP virtual folder cannot be the destination.\n\nCancellation or failure can leave partial results. Inspect the destination and the final operation status before retrying.\n", "2.0": "+++\ntitle = \"Work with ZIP Archives\"\n+++\n\n## Look Inside a ZIP\n\nOpen a ZIP as a virtual folder on an SMB share or paired local drive. Browse its directories and preview supported files inside it without extracting the whole archive. Read-only access is enough for inspection. Local archives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/); SMB archives do not.\n\nSambee cannot preview or extract encrypted members or members with unsupported compression. These members appear in lighter text; hover over a row to see its reason. Use another archive tool, with the password for encrypted members, to access them.\n\n## Download Selected Contents\n\nSelect archive members or folders and choose **Download** to get a new ZIP containing those items. A selected folder includes its contents. This does not create an archive in storage. See [download limits](../download-and-upload-files/#download-limits).\n\n## Extract Selected Members\n\nOn desktop, open the ZIP in the active pane and a writable physical folder in the other pane. Select members and press **F5** to extract them there. Selected directories include all their contents and empty directories. Archive members cannot be moved; **F6** is unavailable and does not modify the ZIP.\n\nExtraction continues for readable members inside a selected folder. The completion notice reports skipped members and gives separate counts for encryption and unsupported compression.\n\nExtraction can leave partial results after failure or cancellation. Inspect the destination before retrying; see [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n\n## Create an Archive in Storage\n\nUnlike a generated download, **Create archive** writes a persistent ZIP into the destination folder. For files selected inside a ZIP, open a writable physical folder on the **same SMB connection** in the other pane, then choose **Create archive**. Creating an archive from ZIP members is not available for local-drive or mixed-connection destinations.\n\nFor ordinary stored files or folders, select the source items and choose **Create archive** with a writable physical destination. Source items must belong to one connection. The action is unavailable for unsupported source or destination combinations; a ZIP virtual folder cannot be the destination.\n\nCancellation or failure can leave partial results. Inspect the destination and the final operation status before retrying.\n"}, "page_contents": {"1.0": "+++\ntitle = \"Work with ZIP Archives\"\n+++\n\n## Look Inside a ZIP\n\nOpen a ZIP as a virtual folder on an SMB share or paired local drive. Browse its directories and preview supported files inside it without extracting the whole archive. Read-only access is enough for inspection. Local archives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/); SMB archives do not.\n\nSambee cannot preview or extract encrypted members or members with unsupported compression. These members appear in lighter text; hover over a row to see its reason. Use another archive tool, with the password for encrypted members, to access them.\n\n## Download Selected Contents\n\nSelect archive members or folders and choose **Download** to get a new ZIP containing those items. A selected folder includes its contents. This does not create an archive in storage. See [download limits](../download-and-upload-files/#download-limits).\n\n## Extract Selected Members\n\nOn desktop, open the ZIP in the active pane and a writable physical folder in the other pane. Select members and press **F5** to extract them there. Selected directories include all their contents and empty directories. Archive members cannot be moved; **F6** is unavailable and does not modify the ZIP.\n\nExtraction continues for readable members inside a selected folder. The completion notice reports skipped members and gives separate counts for encryption and unsupported compression.\n\nExtraction can leave partial results after failure or cancellation. Inspect the destination before retrying; see [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n\n## Create an Archive in Storage\n\nUnlike a generated download, **Create archive** writes a persistent ZIP into the destination folder. For files selected inside a ZIP, open a writable physical folder on the **same SMB connection** in the other pane, then choose **Create archive**. Creating an archive from ZIP members is not available for local-drive or mixed-connection destinations.\n\nFor ordinary stored files or folders, select the source items and choose **Create archive** with a writable physical destination. Source items must belong to one connection. The action is unavailable for unsupported source or destination combinations; a ZIP virtual folder cannot be the destination.\n\nCancellation or failure can leave partial results. Inspect the destination and the final operation status before retrying.\n", "2.0": "+++\ntitle = \"Work with ZIP Archives\"\n+++\n\n## Look Inside a ZIP\n\nOpen a ZIP as a virtual folder on an SMB share or paired local drive. Browse its directories and preview supported files inside it without extracting the whole archive. Read-only access is enough for inspection. Local archives require [Companion](../../use-local-drives-and-desktop-apps/access-local-drives/); SMB archives do not.\n\nSambee cannot preview or extract encrypted members or members with unsupported compression. These members appear in lighter text; hover over a row to see its reason. Use another archive tool, with the password for encrypted members, to access them.\n\n## Download Selected Contents\n\nSelect archive members or folders and choose **Download** to get a new ZIP containing those items. A selected folder includes its contents. This does not create an archive in storage. See [download limits](../download-and-upload-files/#download-limits).\n\n## Extract Selected Members\n\nOn desktop, open the ZIP in the active pane and a writable physical folder in the other pane. Select members and press **F5** to extract them there. Selected directories include all their contents and empty directories. Archive members cannot be moved; **F6** is unavailable and does not modify the ZIP.\n\nExtraction continues for readable members inside a selected folder. The completion notice reports skipped members and gives separate counts for encryption and unsupported compression.\n\nExtraction can leave partial results after failure or cancellation. Inspect the destination before retrying; see [transfer recovery](../../troubleshooting/common-user-problems/#cannot-complete-a-transfer).\n\n## Create an Archive in Storage\n\nUnlike a generated download, **Create archive** writes a persistent ZIP into the destination folder. For files selected inside a ZIP, open a writable physical folder on the **same SMB connection** in the other pane, then choose **Create archive**. Creating an archive from ZIP members is not available for local-drive or mixed-connection destinations.\n\nFor ordinary stored files or folders, select the source items and choose **Create archive** with a writable physical destination. Source items must belong to one connection. The action is unavailable for unsupported source or destination combinations; a ZIP virtual folder cannot be the destination.\n\nCancellation or failure can leave partial results. Inspect the destination and the final operation status before retrying.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/organize-and-transfer-files/share-files-on-phones-and-tablets", "parent_id": "section:user-guide/organize-and-transfer-files", "depth": 2, "kind": "page", "label": "share-files-on-phones-and-tablets", "title": "Share Files On Phones And Tablets", "path": "user-guide/organize-and-transfer-files/share-files-on-phones-and-tablets", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "authored"}}, "content_versions": {"2.0": "+++\ntitle = \"Share Files on Phones and Tablets\"\n+++\n\nOn phones and tablets, Sambee integrates with your device's native sharing functionality so that you can send files to other apps.\n\n## Share Stored Files\n\nChoose **Share** from a file's action menu or the selection menu to prepare the stored files. When they are ready, tap **Share** to open your phone or tablet's share sheet. If you select several files, Sambee sends them together. It does not leave files out of your selection.\n\n## Share from a Viewer or Editor\n\nWhen you share from an image or PDF viewer, Sambee shares the version shown in the viewer. This can differ from the stored file if Sambee converted the image or prepared the PDF for viewing. PDF sharing includes the whole document, not just the current page. To share the original stored file, use **Share** in the file list.\n\nFor text and Markdown, choose what to share:\n\n- **Share as file** sends the saved file. It does not save or include unsaved editor changes.\n- **Share as text** sends the loaded text or current editor contents, including unsaved edits. For Markdown, it sends the Markdown text, not the formatted preview.\n\n## If Sharing Is Unavailable or Fails\n\nEven on phones and tablets, sharing support and accepted files depend on the browser and device. A file can be rejected after preparation. Sambee does not send text instead of a file automatically. Choose **Share as text** when that option is available and you want to send text.\n\nIf sharing is unavailable, including on desktop platforms, use **Download**. You can then send the downloaded file through another app on your device.\n\nIf sharing from a viewer fails, the recovery download gives you the same version you tried to share. For several prepared files, download each file separately. If Sambee cannot prepare a text or Markdown file, **Retry** prepares it again. You must then tap **Share** to open the share sheet.\n\n### Get a Report for Support\n\nChoose **Details** in the failure message to get a diagnostic report. It does not include file names, paths, text, file contents, or credentials. Sambee does not upload it automatically. If you cannot copy the report, select its text manually. Closing **Details** leaves the recovery actions available.\n\n### Cancel or Check Delivery\n\nCancelling your phone or tablet's share sheet is not an error. A completed share request does not confirm delivery. Check the receiving app to confirm that it received the files or text.\n"}, "page_contents": {"2.0": "+++\ntitle = \"Share Files on Phones and Tablets\"\n+++\n\nOn phones and tablets, Sambee integrates with your device's native sharing functionality so that you can send files to other apps.\n\n## Share Stored Files\n\nChoose **Share** from a file's action menu or the selection menu to prepare the stored files. When they are ready, tap **Share** to open your phone or tablet's share sheet. If you select several files, Sambee sends them together. It does not leave files out of your selection.\n\n## Share from a Viewer or Editor\n\nWhen you share from an image or PDF viewer, Sambee shares the version shown in the viewer. This can differ from the stored file if Sambee converted the image or prepared the PDF for viewing. PDF sharing includes the whole document, not just the current page. To share the original stored file, use **Share** in the file list.\n\nFor text and Markdown, choose what to share:\n\n- **Share as file** sends the saved file. It does not save or include unsaved editor changes.\n- **Share as text** sends the loaded text or current editor contents, including unsaved edits. For Markdown, it sends the Markdown text, not the formatted preview.\n\n## If Sharing Is Unavailable or Fails\n\nEven on phones and tablets, sharing support and accepted files depend on the browser and device. A file can be rejected after preparation. Sambee does not send text instead of a file automatically. Choose **Share as text** when that option is available and you want to send text.\n\nIf sharing is unavailable, including on desktop platforms, use **Download**. You can then send the downloaded file through another app on your device.\n\nIf sharing from a viewer fails, the recovery download gives you the same version you tried to share. For several prepared files, download each file separately. If Sambee cannot prepare a text or Markdown file, **Retry** prepares it again. You must then tap **Share** to open the share sheet.\n\n### Get a Report for Support\n\nChoose **Details** in the failure message to get a diagnostic report. It does not include file names, paths, text, file contents, or credentials. Sambee does not upload it automatically. If you cannot copy the report, select its text manually. Closing **Details** leaves the recovery actions available.\n\n### Cancel or Check Delivery\n\nCancelling your phone or tablet's share sheet is not an error. A completed share request does not confirm delivery. Check the receiving app to confirm that it received the files or text.\n"}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/view-and-edit-files", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "view-and-edit-files", "title": "View and Edit Files", "path": "user-guide/view-and-edit-files", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/view-and-edit-files/view-images-and-read-documents", "parent_id": "section:user-guide/view-and-edit-files", "depth": 2, "kind": "page", "label": "view-images-and-read-documents", "title": "View Images And Read Documents", "path": "user-guide/view-and-edit-files/view-images-and-read-documents", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.8": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.9": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "1.0": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "2.0": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n"}, "page_contents": {"0.7": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.8": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.9": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "1.0": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "2.0": "+++\ntitle = \"View Images and Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nPreview Photoshop designs, HEIC photos, and other [supported formats](../../reference/supported-file-formats/) without their desktop apps. Some previews show a converted image, not every part of the source: for example, a PSD shows its flattened composite and a multi-page TIFF shows its first page.\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\nTo use an installed app instead of a preview, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/view-and-edit-files/edit-markdown", "parent_id": "section:user-guide/view-and-edit-files", "depth": 2, "kind": "page", "label": "edit-markdown", "title": "Edit Markdown", "path": "user-guide/view-and-edit-files/edit-markdown", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 1}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 2, "diff_removed": 0}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 33, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.8": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "0.9": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "1.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "2.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. You edit Markdown source directly, with highlighted structure and fenced code. Highlighting doesn't change your source text or line layout.\n\nIf another session holds the edit lock, a bottom-center toast explains why editing isn't available. The **Read only** badge and **Retry editing** icon remain after the informational toast closes automatically after 15 seconds. Click Retry or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e when the other editor is closed. Slow access checks show a small spinner beside the filename without moving the document.\n\nIf the lock is lost while editing, Sambee stops changes and retains your draft. On retry, if the saved file changed, choose **Use saved file** or **Keep my draft**. Keeping your draft doesn't save it; review it before choosing Save.\n\n## Edit Rendered Tables\n\nChange cells, rows, and columns in the rendered table view without aligning Markdown markup. Changes become part of the Markdown source and still require **Save** to reach storage.\n\nFor supported code languages, see [Text File Support and Syntax Highlighting](../../reference/text-file-support-and-syntax-highlighting/). For other text files, see [View and Edit Text Files](../view-and-edit-text-files/).\n\n## Large Documents\n\nLarge Markdown previews appear progressively. You can read the text already displayed or close the viewer while loading continues. Search, editing, heading links and the toolbar's Print action become available when the complete document is ready. Printing from the browser menu before then shows a loading notice instead of an incomplete document.\n\nLarge previews can briefly pause while loading, and code colors can arrive after the text. Large Replace All operations show busy feedback before applying the complete replacement, but the editor and indicator can pause during that step. Editing very large tables can also be slow. These limitations don't shorten the document or split a replacement into separate undo steps.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nFinish any input-method composition before saving. Sambee waits for table-cell edits to reach the document before capturing the saved text. If that can't finish, the editor stays open with your changes rather than saving an incomplete cell. Retry Save after the edit finishes.\n\nYou can keep editing during an ordinary Save. Save writes the revision it captured; edits made afterward remain unsaved. If preparation or writing fails, your changes remain available in the editor.\n\nClosing error feedback does not resolve the problem or discard your changes. A failed Save inside a recovery or unsaved-changes dialog stays in that dialog.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor and return to the viewer. If there are unsaved changes, choose **Save** to save them and return to the viewer, **Discard** to return without saving, or **Cancel** to keep editing. If saving fails, the editor stays open with your changes.\n\nFrom the viewer, click the X icon again to return to the file list. This two-step sequence applies to Markdown only. The text editor opens directly and closes straight to the file list, with the same Save, Discard, and Cancel choices for unsaved changes.\n\n## Print Or Save As PDF\n\nIn the Markdown viewer, click the printer icon to open your browser's print dialog. Choose a printer or **Save as PDF** if your browser offers it. You can also use **Print** from the browser menu. Paper size, margins and headers/footers are controlled by that dialog. The suggested PDF filename uses the Markdown document's name when supported by your browser.\n\nThe output contains the rendered document, without Sambee's toolbar or file browser. Text prints black on white in both themes, with compact text sizes independent of the screen view. Long code lines and table cells wrap to fit the page, and images are included. Printing doesn't modify the Markdown file.\n\nPrint is available in the viewer, not the editor. To print your latest changes, save them and return to the viewer first. Closing or cancelling the print dialog leaves the viewer open.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.8": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "0.9": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "1.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nUse **Edit** or **E** in the Markdown viewer to edit source. Tables can be changed in their rendered table view: edit cells and add or remove rows and columns without aligning Markdown markup. The result stays a Markdown file in its original storage.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n\nEditing requires write access and a file lock. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/) if editing is unavailable. For other text formats, see [View and Edit Text Files](../view-and-edit-text-files/).\n", "2.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. You edit Markdown source directly, with highlighted structure and fenced code. Highlighting doesn't change your source text or line layout.\n\nIf another session holds the edit lock, a bottom-center toast explains why editing isn't available. The **Read only** badge and **Retry editing** icon remain after the informational toast closes automatically after 15 seconds. Click Retry or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e when the other editor is closed. Slow access checks show a small spinner beside the filename without moving the document.\n\nIf the lock is lost while editing, Sambee stops changes and retains your draft. On retry, if the saved file changed, choose **Use saved file** or **Keep my draft**. Keeping your draft doesn't save it; review it before choosing Save.\n\n## Edit Rendered Tables\n\nChange cells, rows, and columns in the rendered table view without aligning Markdown markup. Changes become part of the Markdown source and still require **Save** to reach storage.\n\nFor supported code languages, see [Text File Support and Syntax Highlighting](../../reference/text-file-support-and-syntax-highlighting/). For other text files, see [View and Edit Text Files](../view-and-edit-text-files/).\n\n## Large Documents\n\nLarge Markdown previews appear progressively. You can read the text already displayed or close the viewer while loading continues. Search, editing, heading links and the toolbar's Print action become available when the complete document is ready. Printing from the browser menu before then shows a loading notice instead of an incomplete document.\n\nLarge previews can briefly pause while loading, and code colors can arrive after the text. Large Replace All operations show busy feedback before applying the complete replacement, but the editor and indicator can pause during that step. Editing very large tables can also be slow. These limitations don't shorten the document or split a replacement into separate undo steps.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nFinish any input-method composition before saving. Sambee waits for table-cell edits to reach the document before capturing the saved text. If that can't finish, the editor stays open with your changes rather than saving an incomplete cell. Retry Save after the edit finishes.\n\nYou can keep editing during an ordinary Save. Save writes the revision it captured; edits made afterward remain unsaved. If preparation or writing fails, your changes remain available in the editor.\n\nClosing error feedback does not resolve the problem or discard your changes. A failed Save inside a recovery or unsaved-changes dialog stays in that dialog.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor and return to the viewer. If there are unsaved changes, choose **Save** to save them and return to the viewer, **Discard** to return without saving, or **Cancel** to keep editing. If saving fails, the editor stays open with your changes.\n\nFrom the viewer, click the X icon again to return to the file list. This two-step sequence applies to Markdown only. The text editor opens directly and closes straight to the file list, with the same Save, Discard, and Cancel choices for unsaved changes.\n\n## Print Or Save As PDF\n\nIn the Markdown viewer, click the printer icon to open your browser's print dialog. Choose a printer or **Save as PDF** if your browser offers it. You can also use **Print** from the browser menu. Paper size, margins and headers/footers are controlled by that dialog. The suggested PDF filename uses the Markdown document's name when supported by your browser.\n\nThe output contains the rendered document, without Sambee's toolbar or file browser. Text prints black on white in both themes, with compact text sizes independent of the screen view. Long code lines and table cells wrap to fit the page, and images are included. Printing doesn't modify the Markdown file.\n\nPrint is available in the viewer, not the editor. To print your latest changes, save them and return to the viewer first. Closing or cancelling the print dialog leaves the viewer open.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/view-and-edit-files/file-locking-and-conflict-resolution", "parent_id": "section:user-guide/view-and-edit-files", "depth": 2, "kind": "page", "label": "file-locking-and-conflict-resolution", "title": "File Locking And Conflict Resolution", "path": "user-guide/view-and-edit-files/file-locking-and-conflict-resolution", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 7, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.8": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.9": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "1.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "2.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Browser Editing\n\nSambee acquires an edit lock before you can edit Markdown or plain-text files. Sambee releases the lock when you leave the editor.\n\nIf another session already holds the lock, the file stays read-only. Use **Retry editing** once the other session has finished.\n\nWhile you're editing, Sambee renews the lock every 30 seconds. Short interruptions retry silently without interrupting your work. After three consecutive renewal failures, a warning appears. It clears when renewal succeeds, and saving still checks the lock.\n\nIf the server confirms that the lock is no longer active or write permission has been denied, the editor immediately becomes read-only and keeps your draft. Use **Retry editing** to regain access. If the saved file changed in the meantime, Sambee asks how to resolve the difference before you continue.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.8": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.9": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "1.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "2.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Browser Editing\n\nSambee acquires an edit lock before you can edit Markdown or plain-text files. Sambee releases the lock when you leave the editor.\n\nIf another session already holds the lock, the file stays read-only. Use **Retry editing** once the other session has finished.\n\nWhile you're editing, Sambee renews the lock every 30 seconds. Short interruptions retry silently without interrupting your work. After three consecutive renewal failures, a warning appears. It clears when renewal succeeds, and saving still checks the lock.\n\nIf the server confirms that the lock is no longer active or write permission has been denied, the editor immediately becomes read-only and keeps your draft. Use **Retry editing** to regain access. If the saved file changed in the meantime, Sambee asks how to resolve the difference before you continue.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/view-and-edit-files/view-and-edit-text-files", "parent_id": "section:user-guide/view-and-edit-files", "depth": 2, "kind": "page", "label": "view-and-edit-text-files", "title": "View And Edit Text Files", "path": "user-guide/view-and-edit-files/view-and-edit-text-files", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "authored"}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 13, "diff_removed": 5}}, "content_versions": {"0.8": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "0.9": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "1.0": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "2.0": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files directly in their existing storage. **Save** writes to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/). See [Text File Support and Syntax Highlighting](../../reference/text-file-support-and-syntax-highlighting/) for formats and limits, or [Edit Markdown](../edit-markdown/) for rendered table editing.\n\n## Saving and Locks\n\nFiles without write permission, files on read-only connections, ZIP members, and files above the configured editing limit stay read-only. You can still read or download them.\n\nEditing requires a file lock. If editing is unavailable, close the other edit session, then use **Retry editing**. If the lock is lost, Sambee stops changes and retains your draft. If the saved file changed, choose **Use saved file** or **Keep my draft** when retrying. Keeping a draft does not save it; review it before Save. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/).\n\nYou can edit during an ordinary Save. Save writes the revision captured when it began; later edits remain unsaved. A failed save keeps your changes in the editor. Finish input-method composition before saving.\n\n## Unsaved Changes and Recovery\n\nThe text editor closes directly to the file list. With unsaved changes, **Save** writes them before leaving, **Discard** leaves without saving, and **Cancel** keeps editing. A failed save keeps the editor open. Navigation does not undo saved changes or restore discarded edits.\n\nIf sign-in interrupts editing, eligible drafts can be stored in this browser tab. Recovery is not a substitute for saving. See [Recover Unsaved Edits](../recover-unsaved-edits/).\n\nFor an installed application instead, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n"}, "page_contents": {"0.8": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "0.9": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "1.0": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files in their existing storage, without downloading a separate copy. The text editor writes back to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\nUse the text editor for supported text formats and [Edit Markdown](../edit-markdown/) for rendered Markdown tables. See [Supported File Formats](../../reference/supported-file-formats/) if a file opens in another viewer.\n\n## Save to Storage\n\n**Save** writes your changes to the original file. Changes not yet saved are not in storage. Editing obtains a file lock; if the file is locked or your session loses its lock, see [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/). Keep your draft until you can save it or preserve a separate copy.\n\nLeaving with unsaved changes asks whether to save them. Do not treat browser navigation as an undo of changes already saved.\n", "2.0": "+++\ntitle = \"View and Edit Text Files\"\n+++\n\nEdit supported text files directly in their existing storage. **Save** writes to the source file; read-only storage cannot be edited. Local files require [Companion access](../../use-local-drives-and-desktop-apps/access-local-drives/). See [Text File Support and Syntax Highlighting](../../reference/text-file-support-and-syntax-highlighting/) for formats and limits, or [Edit Markdown](../edit-markdown/) for rendered table editing.\n\n## Saving and Locks\n\nFiles without write permission, files on read-only connections, ZIP members, and files above the configured editing limit stay read-only. You can still read or download them.\n\nEditing requires a file lock. If editing is unavailable, close the other edit session, then use **Retry editing**. If the lock is lost, Sambee stops changes and retains your draft. If the saved file changed, choose **Use saved file** or **Keep my draft** when retrying. Keeping a draft does not save it; review it before Save. See [File Locking and Conflict Resolution](../file-locking-and-conflict-resolution/).\n\nYou can edit during an ordinary Save. Save writes the revision captured when it began; later edits remain unsaved. A failed save keeps your changes in the editor. Finish input-method composition before saving.\n\n## Unsaved Changes and Recovery\n\nThe text editor closes directly to the file list. With unsaved changes, **Save** writes them before leaving, **Discard** leaves without saving, and **Cancel** keeps editing. A failed save keeps the editor open. Navigation does not undo saved changes or restore discarded edits.\n\nIf sign-in interrupts editing, eligible drafts can be stored in this browser tab. Recovery is not a substitute for saving. See [Recover Unsaved Edits](../recover-unsaved-edits/).\n\nFor an installed application instead, see [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/view-and-edit-files/recover-unsaved-edits", "parent_id": "section:user-guide/view-and-edit-files", "depth": 2, "kind": "page", "label": "recover-unsaved-edits", "title": "Recover Unsaved Edits", "path": "user-guide/view-and-edit-files/recover-unsaved-edits", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 36, "diff_removed": 3}}, "content_versions": {"0.9": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "1.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "2.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\nThe pre-sign-in snapshot is a best-effort attempt. Sign-in continues even if a draft cannot be stored; it does not wait for unfinished editor input or save the file. Save important work regularly.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- When Sambee offers an unsaved local draft, choose **Resume editing** to return to it, or **Discard draft** to keep the saved file.\n- If the remote file changed, review the recovery choice carefully. Sambee doesn't overwrite the remote version automatically.\n- Save the restored draft when you're ready. Sambee removes its recovery copy once the current draft is saved or when you deliberately discard it. Edits made while an earlier save is still in progress remain unsaved.\n\n## Recovery Limits\n\n### Moved or Deleted Files\n\nIf the file or its folder is moved or deleted while you edit, keep the editor open. A directory refresh can open an accessible parent folder without closing the editor or changing its unsaved text.\n\nSave from an active edit session can recreate a deleted file at its original path. It does not follow a moved file to its new location. SMB saves require the parent folder to exist; local-drive saves can recreate parent folders on an available drive.\n\nA failed save keeps the draft. Use the available draft recovery or download action to keep your work. If editing becomes unavailable, use the explicit editing retry action and review any conflict before saving. Sambee does not silently acquire a new lock after a failed save.\n\nAccess errors and connection failures do not mean the file was deleted. Check access or restore the connection, then retry. Do not discard the draft unless you no longer need its changes.\n\nA normal save can overwrite changes made at the same file path. Sambee does not check for all external changes before each write. If the write succeeds but updated file information cannot be read, the save remains successful; Sambee does not repeat the write automatically.\n\n### Notifications and Connection Recovery\n\nRecovery notifications appear at the bottom center of the application, not inside a browser pane. Informational results, including automatic parent-folder recovery, close after 6 seconds. Browser failures, pairing notices, monitoring failures, and connection status notices close after 10 seconds. Editor errors and safety warnings, including save failures, close after 15 seconds. The timer pauses while you point to the notification or use its controls with the keyboard. Closing a notification does not save a draft, restore a connection, or remove recovery data. Use Next notification when more than one condition needs attention.\n\nFile and folder failure notifications show the problem first. A smaller line below it identifies the connection and failed file or folder. Long paths are shortened to fit on one line, keeping the connection and the end of the path where space permits. Point to a shortened value to see the complete path from the connection's root. The full value also remains available to screen readers. The path identifies the failed target, not a different folder that you opened later. After automatic parent-folder recovery, this line still identifies the original missing folder.\n\nNotifications stay open without a timer only while they provide Cancel for an active upload, download, or share preparation, or Share and Cancel for files ready to share. Sharing after confirmation uses the normal 6-second information timeout. A notification closing does not cancel an active operation. Unsaved-change and other decision dialogs do not close on a timer.\n\nRetry applies to the file or folder that failed, even after you select another row or pane. A failed folder navigation keeps the previous usable folder visible. If no folder can load, the list area shows the error and recovery actions instead of an empty list. A folder that loaded with no files remains a normal empty folder.\n\nRefresh reloads the displayed folder. It does not repeat a failed file launch or open a different failed folder. The existing header warning control opens connection recovery actions after a notification closes automatically or you close it manually. No additional warning or progress controls are added when a notification closes.\n\nIf automatic updates stop, use **Automatic updates stopped** to retry monitoring. This control remains available after you close its notification. Monitoring is active again only after the subscription is confirmed. A backend connection status distinguishes reconnection from unavailability. Companion recovery remains available through Local Drives, including when no editor is open. A signature error can require **Reload Sambee**. Unsaved changes still require your decision before reload.\n\nIf a document cannot load, its viewer shows the error with Retry and Close. A missing image in the gallery shows an error for that image; use Retry, select another image, or close the viewer. Sambee does not keep the previous document open until the next document finishes loading.\n\n### Browser Storage\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\nAn unfinished edit may not be recoverable when the browser suspends or terminates the page. A successful recovery checkpoint isn't a file save or a guarantee that the draft will survive closing the tab.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "1.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "2.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\nThe pre-sign-in snapshot is a best-effort attempt. Sign-in continues even if a draft cannot be stored; it does not wait for unfinished editor input or save the file. Save important work regularly.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- When Sambee offers an unsaved local draft, choose **Resume editing** to return to it, or **Discard draft** to keep the saved file.\n- If the remote file changed, review the recovery choice carefully. Sambee doesn't overwrite the remote version automatically.\n- Save the restored draft when you're ready. Sambee removes its recovery copy once the current draft is saved or when you deliberately discard it. Edits made while an earlier save is still in progress remain unsaved.\n\n## Recovery Limits\n\n### Moved or Deleted Files\n\nIf the file or its folder is moved or deleted while you edit, keep the editor open. A directory refresh can open an accessible parent folder without closing the editor or changing its unsaved text.\n\nSave from an active edit session can recreate a deleted file at its original path. It does not follow a moved file to its new location. SMB saves require the parent folder to exist; local-drive saves can recreate parent folders on an available drive.\n\nA failed save keeps the draft. Use the available draft recovery or download action to keep your work. If editing becomes unavailable, use the explicit editing retry action and review any conflict before saving. Sambee does not silently acquire a new lock after a failed save.\n\nAccess errors and connection failures do not mean the file was deleted. Check access or restore the connection, then retry. Do not discard the draft unless you no longer need its changes.\n\nA normal save can overwrite changes made at the same file path. Sambee does not check for all external changes before each write. If the write succeeds but updated file information cannot be read, the save remains successful; Sambee does not repeat the write automatically.\n\n### Notifications and Connection Recovery\n\nRecovery notifications appear at the bottom center of the application, not inside a browser pane. Informational results, including automatic parent-folder recovery, close after 6 seconds. Browser failures, pairing notices, monitoring failures, and connection status notices close after 10 seconds. Editor errors and safety warnings, including save failures, close after 15 seconds. The timer pauses while you point to the notification or use its controls with the keyboard. Closing a notification does not save a draft, restore a connection, or remove recovery data. Use Next notification when more than one condition needs attention.\n\nFile and folder failure notifications show the problem first. A smaller line below it identifies the connection and failed file or folder. Long paths are shortened to fit on one line, keeping the connection and the end of the path where space permits. Point to a shortened value to see the complete path from the connection's root. The full value also remains available to screen readers. The path identifies the failed target, not a different folder that you opened later. After automatic parent-folder recovery, this line still identifies the original missing folder.\n\nNotifications stay open without a timer only while they provide Cancel for an active upload, download, or share preparation, or Share and Cancel for files ready to share. Sharing after confirmation uses the normal 6-second information timeout. A notification closing does not cancel an active operation. Unsaved-change and other decision dialogs do not close on a timer.\n\nRetry applies to the file or folder that failed, even after you select another row or pane. A failed folder navigation keeps the previous usable folder visible. If no folder can load, the list area shows the error and recovery actions instead of an empty list. A folder that loaded with no files remains a normal empty folder.\n\nRefresh reloads the displayed folder. It does not repeat a failed file launch or open a different failed folder. The existing header warning control opens connection recovery actions after a notification closes automatically or you close it manually. No additional warning or progress controls are added when a notification closes.\n\nIf automatic updates stop, use **Automatic updates stopped** to retry monitoring. This control remains available after you close its notification. Monitoring is active again only after the subscription is confirmed. A backend connection status distinguishes reconnection from unavailability. Companion recovery remains available through Local Drives, including when no editor is open. A signature error can require **Reload Sambee**. Unsaved changes still require your decision before reload.\n\nIf a document cannot load, its viewer shows the error with Retry and Close. A missing image in the gallery shows an error for that image; use Retry, select another image, or close the viewer. Sambee does not keep the previous document open until the next document finishes loading.\n\n### Browser Storage\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\nAn unfinished edit may not be recoverable when the browser suspends or terminates the page. A successful recovery checkpoint isn't a file save or a guarantee that the draft will survive closing the tab.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/use-local-drives-and-desktop-apps", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "use-local-drives-and-desktop-apps", "title": "Use Local Drives and Desktop Apps", "path": "user-guide/use-local-drives-and-desktop-apps", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/use-local-drives-and-desktop-apps/install-and-pair-the-companion-app", "parent_id": "section:user-guide/use-local-drives-and-desktop-apps", "depth": 2, "kind": "page", "label": "install-and-pair-the-companion-app", "title": "Install And Pair The Companion App", "path": "user-guide/use-local-drives-and-desktop-apps/install-and-pair-the-companion-app", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 17, "diff_removed": 4}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 21, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair This Browser With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee and Companion both display a verification code. Confirm that both codes match, then finish pairing. Sambee should now show a check mark next to **This browser is paired**.\n\nPairing is scoped to the current browser origin and browser profile, not to the whole computer. If you use Sambee from a different browser, a different browser profile, or a different Sambee site origin, approve that browser separately.\n\nOnce this browser is paired with Companion, local drives on your computer appear in Sambee's connection list.\n", "0.8": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "0.9": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "1.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "2.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\nOpen Sambee over HTTPS before pairing from another computer or a network address. Browsers don't provide the cryptographic APIs needed by Companion on ordinary HTTP sites. Local development on `http://localhost` is an exception. If **Local Drives** warns that a secure browser context with Web Crypto support is unavailable, use HTTPS; if you're already using HTTPS, check that your browser supports and permits Web Crypto. You don't need HTTPS to download the Companion installer.\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nPairing also lets that server manage Companion theme, localization, and directory-search settings. The most recently paired server is authoritative, even if other servers remain paired for file access. Pair the intended server again to change authority. No separate settings approval is required.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee verifies local access and shows a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- Settings synchronize automatically while a signed-in Sambee tab is active. Failed delivery keeps the last valid settings; it does not disable directory search.\n- Removing the authoritative pairing keeps the last valid settings but does not select another server automatically.\n\n## Restore Local-Drive Access\n\nIf a local drive reports a pairing error, open **Settings** \u003e **Local Drives** from the file-list alert. **Ready** means the browser has passed an authenticated pairing check; having a stored pairing alone is not enough.\n\n1. If Companion needs an update, install the available version, restart Companion, and reload the Sambee page. Re-pairing will not resolve an incompatible version.\n1. If Sambee needs an update, reload the page. If the version mismatch remains, update Sambee. Updating Companion or re-pairing will not fix a newer Companion protocol.\n1. If the file-list alert says this browser isn't paired, open **Local Drives** and select **Pair This Browser**. Reloading alone won't restore a missing or removed pairing.\n1. If Companion rejects the browser's signature, reload the Sambee page first. A page left open across an update may still use the previous authentication protocol.\n1. Run **Test Current Pairing**. If it still fails with a signature error after reloading, use **Pair This Browser** and approve the new code in Companion.\n\nIf Sambee cannot check the pairing status, select **Retry**. Wait for a confirmed status before starting a new pairing. Companion pairing secrets do not expire on a 30-day timer. An unavailable Companion or a temporary failed check does not mean you need to re-pair.\n\nIf settings show **Pairing required**, Companion could not authenticate this browser. Automatic settings checks pause to avoid repeated failed requests. Follow the pairing recovery steps above. Successful pairing restarts settings synchronization; **Retry** starts a new check without removing the stored pairing or settings.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair This Browser With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee and Companion both display a verification code. Confirm that both codes match, then finish pairing. Sambee should now show a check mark next to **This browser is paired**.\n\nPairing is scoped to the current browser origin and browser profile, not to the whole computer. If you use Sambee from a different browser, a different browser profile, or a different Sambee site origin, approve that browser separately.\n\nOnce this browser is paired with Companion, local drives on your computer appear in Sambee's connection list.\n", "0.8": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "0.9": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "1.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "2.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\nOpen Sambee over HTTPS before pairing from another computer or a network address. Browsers don't provide the cryptographic APIs needed by Companion on ordinary HTTP sites. Local development on `http://localhost` is an exception. If **Local Drives** warns that a secure browser context with Web Crypto support is unavailable, use HTTPS; if you're already using HTTPS, check that your browser supports and permits Web Crypto. You don't need HTTPS to download the Companion installer.\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nPairing also lets that server manage Companion theme, localization, and directory-search settings. The most recently paired server is authoritative, even if other servers remain paired for file access. Pair the intended server again to change authority. No separate settings approval is required.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee verifies local access and shows a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- Settings synchronize automatically while a signed-in Sambee tab is active. Failed delivery keeps the last valid settings; it does not disable directory search.\n- Removing the authoritative pairing keeps the last valid settings but does not select another server automatically.\n\n## Restore Local-Drive Access\n\nIf a local drive reports a pairing error, open **Settings** \u003e **Local Drives** from the file-list alert. **Ready** means the browser has passed an authenticated pairing check; having a stored pairing alone is not enough.\n\n1. If Companion needs an update, install the available version, restart Companion, and reload the Sambee page. Re-pairing will not resolve an incompatible version.\n1. If Sambee needs an update, reload the page. If the version mismatch remains, update Sambee. Updating Companion or re-pairing will not fix a newer Companion protocol.\n1. If the file-list alert says this browser isn't paired, open **Local Drives** and select **Pair This Browser**. Reloading alone won't restore a missing or removed pairing.\n1. If Companion rejects the browser's signature, reload the Sambee page first. A page left open across an update may still use the previous authentication protocol.\n1. Run **Test Current Pairing**. If it still fails with a signature error after reloading, use **Pair This Browser** and approve the new code in Companion.\n\nIf Sambee cannot check the pairing status, select **Retry**. Wait for a confirmed status before starting a new pairing. Companion pairing secrets do not expire on a 30-day timer. An unavailable Companion or a temporary failed check does not mean you need to re-pair.\n\nIf settings show **Pairing required**, Companion could not authenticate this browser. Automatic settings checks pause to avoid repeated failed requests. Follow the pairing recovery steps above. Successful pairing restarts settings synchronization; **Retry** starts a new check without removing the stored pairing or settings.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/use-local-drives-and-desktop-apps/access-local-drives", "parent_id": "section:user-guide/use-local-drives-and-desktop-apps", "depth": 2, "kind": "page", "label": "access-local-drives", "title": "Access Local Drives", "path": "user-guide/use-local-drives-and-desktop-apps/access-local-drives", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.8": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.9": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "1.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "2.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.8": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.9": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "1.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "2.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/use-local-drives-and-desktop-apps/edit-files-in-desktop-apps", "parent_id": "section:user-guide/use-local-drives-and-desktop-apps", "depth": 2, "kind": "page", "label": "edit-files-in-desktop-apps", "title": "Edit Files In Desktop Apps", "path": "user-guide/use-local-drives-and-desktop-apps/edit-files-in-desktop-apps", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "0.8": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "0.9": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "1.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "2.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "0.8": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "0.9": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "1.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n", "2.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nFor an SMB connection, Companion opens a temporary local copy. Your explicit upload returns changes to the original share; this is not automatic synchronization.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\nCompanion locks the SMB file for the session and shows **Done Editing** beside the installed app. You need write access to upload edits. For local-drive access, also complete [browser pairing](../install-and-pair-the-companion-app/).\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../use-local-drives-and-desktop-apps/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n\nPreserve any unsent local work before reopening. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) for recovery.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/use-local-drives-and-desktop-apps/desktop-app-picker", "parent_id": "section:user-guide/use-local-drives-and-desktop-apps", "depth": 2, "kind": "page", "label": "desktop-app-picker", "title": "Desktop App Picker", "path": "user-guide/use-local-drives-and-desktop-apps/desktop-app-picker", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.8": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.9": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "1.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "2.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.8": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.9": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "1.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "2.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/troubleshooting", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "troubleshooting", "title": "Troubleshooting", "path": "user-guide/troubleshooting", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/troubleshooting/common-user-problems", "parent_id": "section:user-guide/troubleshooting", "depth": 2, "kind": "page", "label": "common-user-problems", "title": "Common User Problems", "path": "user-guide/troubleshooting/common-user-problems", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 6, "diff_removed": 9}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 1, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing for the current browser profile.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If the browser is not paired, start pairing again for this browser.\n1. If Local Drives reports that pairing needs repair, repair the pairing so Sambee can store a fresh browser-side secret.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe desktop-editing session may have expired or been interrupted.\n\nTypical signs are that the **Done Editing** window says the session expired, authentication failed, the lock was lost, or recovery is required.\n\nStart by reopening the file from Sambee so Companion can establish a fresh edit session and lock context.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "0.8": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "0.9": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "1.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "2.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files on Phones and Tablets](../../organize-and-transfer-files/share-files-on-phones-and-tablets/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing for the current browser profile.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If the browser is not paired, start pairing again for this browser.\n1. If Local Drives reports that pairing needs repair, repair the pairing so Sambee can store a fresh browser-side secret.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe desktop-editing session may have expired or been interrupted.\n\nTypical signs are that the **Done Editing** window says the session expired, authentication failed, the lock was lost, or recovery is required.\n\nStart by reopening the file from Sambee so Companion can establish a fresh edit session and lock context.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "0.8": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "0.9": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "1.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files and Links](../../organize-and-transfer-files/share-files-and-links/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n", "2.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Cannot Sign In\n\nUse the sign-in method supplied by your administrator. If local password sign-in is unavailable, use your organization's identity provider. Ask your administrator to check your account and site authentication if sign-in fails repeatedly.\n\n## Cannot See a Connection\n\nAsk the connection owner or administrator to check visibility and your access. A shared connection does not grant file-server permissions. See [Open Connections and Browse Folders](../../find-and-browse-files/connect-to-an-smb-share/).\n\n## Cannot Open a File\n\nCheck that the connection is available and the file still exists. If its viewer does not support the format, download the original or use an installed desktop app. See [Supported File Formats](../../reference/supported-file-formats/).\n\n## Cannot Save\n\nCheck write access and close other edit sessions for that file. Preserve unsaved work before reloading or signing out. See [File Locking and Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/) and [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/).\n\n## Cannot Complete a Transfer\n\nInspect both source and destination after failure or cancellation. Earlier completed items can remain. Do not repeat a move or delete a source until you know which copies are complete. Keep files whose status is uncertain and ask for help with the reported error. See [Copy and Move Files](../../organize-and-transfer-files/copy-and-move-files/).\n\n## Cannot Share\n\nIf the browser or device cannot share an attachment, download it and use your device's file app. Sending a location link does not grant access. See [Share Files on Phones and Tablets](../../organize-and-transfer-files/share-files-on-phones-and-tablets/).\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) and [Access Local Drives](../../use-local-drives-and-desktop-apps/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../use-local-drives-and-desktop-apps/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../view-and-edit-files/file-locking-and-conflict-resolution/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/reference", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "reference", "title": "Reference", "path": "user-guide/reference", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/reference/supported-file-formats", "parent_id": "section:user-guide/reference", "depth": 2, "kind": "page", "label": "supported-file-formats", "title": "Supported File Formats", "path": "user-guide/reference/supported-file-formats", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 2, "diff_removed": 0}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "branched", "source_version": "0.8", "diff_added": 11, "diff_removed": 3}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 1, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "0.8": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "0.9": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "1.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "2.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code | See [Text File Support and Syntax Highlighting](../text-file-support-and-syntax-highlighting/) for extensions, filename matches, and plain-text formats. | Open directly in the text editor, read-only when editing isn't available. Dedicated viewers and saved viewer preferences take precedence. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "0.8": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "0.9": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "1.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n", "2.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code | See [Text File Support and Syntax Highlighting](../text-file-support-and-syntax-highlighting/) for extensions, filename matches, and plain-text formats. | Open directly in the text editor, read-only when editing isn't available. Dedicated viewers and saved viewer preferences take precedence. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../view-and-edit-files/view-images-and-read-documents/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/reference/text-file-support-and-syntax-highlighting", "parent_id": "section:user-guide/reference", "depth": 2, "kind": "page", "label": "text-file-support-and-syntax-highlighting", "title": "Text File Support And Syntax Highlighting", "path": "user-guide/reference/text-file-support-and-syntax-highlighting", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "authored"}}, "content_versions": {"2.0": "+++\ntitle = \"Text File Support and Syntax Highlighting\"\n+++\n\nUse this reference to check which files open in the text editor and which language labels you can use in Markdown code blocks. Sambee uses the same syntax highlighting for the text editor, Markdown source, and code blocks in Markdown previews.\n\n## Text File Support\n\nFiles with an extension or special filename listed below open in the text editor by default, with two exceptions: `.md` and `.markdown` open in the Markdown viewer, and `.svg` opens in the image viewer. A saved viewer preference or the file's MIME type can override the filename-based choice.\n\nThe filename also selects the highlighting language:\n\n- Special filenames take priority over extensions. Their case rules vary: `Dockerfile` requires that spelling, while `nginx.conf` matches in any case.\n- Extensions aren't case-sensitive. Only the final suffix counts, so `project.cmake.in` uses Properties highlighting through `.in`, not CMake.\n- Shared extensions select one language: `.m` uses Mathematica, `.sig` uses PGP, and `.v` uses SystemVerilog.\n\nPlain-text formats such as `.txt` and `.log` open in the text editor without highlighting. Unmatched files don't automatically open as text, but you can choose the text editor from the viewer picker; without a language match, they use plain text.\n\nFor images, PDFs, archives, and other supported formats, see [Supported File Formats](../supported-file-formats/).\n\n## Markdown Code Block Languages\n\nPut a language label immediately after the opening three backticks. For example, `py` selects Python:\n\n````markdown\n```py\ndef greet(name):\n\treturn f\"Hello, {name}!\"\n```\n````\n\nLabels aren't case-sensitive. Labels on the same table row are interchangeable, so `python` works just like `py`. Sambee reads only the first whitespace-separated word after the opening fence; a language's full name works only if it's listed as a label.\n\nUnlabelled blocks and unknown labels use plain text. To request plain text explicitly, use `text`, `txt`, `plaintext`, `plain`, or `none`. Very large code blocks can also remain plain text without losing their contents.\n\n## File and Language Reference\n\nUse the file column to look up a file and the Markdown column to choose a code block label. **None** in the file or viewer column means the language is available only in Markdown code blocks. **None** in the Markdown column means there's no accepted code block label for that format. Viewer choices assume no MIME-type or saved-preference override.\n\n| Language or format | File extensions or names | Markdown labels | Default viewer |\n|---|---|---|---|\n| APL | `.dyalog`, `.apl` | `apl` | Text |\n| ASN.1 | `.asn`, `.asn1` | `asn.1` | Text |\n| Asterisk | `extensions.conf` | `asterisk` | Text |\n| Brainfuck | `.b`, `.bf` | `brainfuck` | Text |\n| C | `.c`, `.h`, `.ino` | `c` | Text |\n| C# | `.cs` | `cs`, `csharp`, `c#` | Text |\n| C++ | `.cpp`, `.c++`, `.cc`, `.cxx`, `.hpp`, `.h++`, `.hh`, `.hxx` | `cpp`, `c++` | Text |\n| Clojure | `.clj`, `.cljc`, `.cljx` | `clojure` | Text |\n| ClojureScript | `.cljs` | `clojurescript` | Text |\n| Closure Stylesheets (GSS) | `.gss` | None | Text |\n| CMake | `.cmake`, `CMakeLists.txt` | `cmake` | Text |\n| COBOL | `.cob`, `.cpy` | `cobol` | Text |\n| CoffeeScript | `.coffee` | `coffee`, `coffee-script`, `coffeescript` | Text |\n| Common Lisp | `.cl`, `.lisp`, `.el` | `lisp` | Text |\n| CQL (Cassandra) | `.cql` | `cql`, `cassandra` | Text |\n| Crystal | `.cr` | `crystal` | Text |\n| CSS | `.css` | `css` | Text |\n| Cypher | `.cyp`, `.cypher` | `cypher` | Text |\n| Cython | `.pyx`, `.pxd`, `.pxi` | `cython` | Text |\n| D | `.d` | `d` | Text |\n| Dart | `.dart` | `dart` | Text |\n| Diff | `.diff`, `.patch` | `diff` | Text |\n| Dockerfile | `Dockerfile` | `docker`, `dockerfile` | Text |\n| DTD | `.dtd` | `dtd` | Text |\n| Dylan | `.dylan`, `.dyl`, `.intr` | `dylan` | Text |\n| EBNF | None | `ebnf` | None |\n| ECL | `.ecl` | `ecl` | Text |\n| edn | `.edn` | `edn` | Text |\n| Eiffel | `.e` | `eiffel` | Text |\n| Elm | `.elm` | `elm` | Text |\n| Erlang | `.erl` | `erlang` | Text |\n| Esper | None | `esper` | None |\n| F# | `.fs` | `fsharp`, `f#` | Text |\n| Factor | `.factor` | `factor` | Text |\n| FCL | None | `fcl` | None |\n| Forth | `.forth`, `.fth`, `.4th` | `forth` | Text |\n| Fortran | `.f`, `.for`, `.f77`, `.f90`, `.f95` | `fortran` | Text |\n| Gas (GNU assembler) | `.s` | `gas` | Text |\n| Gherkin | `.feature` | `gherkin` | Text |\n| Go | `.go` | `go` | Text |\n| Groovy | `.groovy`, `.gradle`, `Jenkinsfile` | `groovy` | Text |\n| Haskell | `.hs` | `haskell` | Text |\n| Haxe | `.hx` | `haxe` | Text |\n| HTML | `.html`, `.htm`, `.handlebars`, `.hbs` | `html`, `htm`, `xhtml` | Text |\n| HTTP | None | `http` | None |\n| HXML | `.hxml` | `hxml` | Text |\n| IDL | `.pro` | `idl` | Text |\n| Java | `.java` | `java` | Text |\n| JavaScript | `.js`, `.mjs`, `.cjs` | `js`, `javascript`, `ecmascript`, `node` | Text |\n| Jinja | `.j2`, `.jinja`, `.jinja2` | `jinja` | Text |\n| JSON | `.json`, `.map` | `json`, `json5` | Text |\n| JSON-LD | `.jsonld` | `jsonld`, `json-ld` | Text |\n| JSX | `.jsx` | `jsx` | Text |\n| Julia | `.jl` | `julia` | Text |\n| Kotlin | `.kt`, `.kts` | `kt`, `kotlin` | Text |\n| LaTeX | `.text`, `.ltx`, `.tex` | `tex`, `latex` | Text |\n| LESS | `.less` | `less` | Text |\n| Liquid | `.liquid` | `liquid` | Text |\n| LiveScript | `.ls` | `ls`, `livescript` | Text |\n| Lua | `.lua` | `lua` | Text |\n| MariaDB SQL | None | `mariadb` | None |\n| Markdown | `.md`, `.markdown` | `md`, `markdown` | Markdown |\n| Markdown source | `.mkd` | `md`, `markdown` | Text |\n| Mathematica | `.m`, `.nb`, `.wl`, `.wls` | `mathematica` | Text |\n| Mbox | `.mbox` | `mbox` | Text |\n| mIRC | `.mrc` | `mirc` | Text |\n| Modelica | `.mo` | `modelica` | Text |\n| MS SQL | None | `mssql` | None |\n| MscGen | `.mscgen`, `.mscin`, `.msc` | `mscgen` | Text |\n| MsGenny | `.msgenny` | `msgenny` | Text |\n| MUMPS | `.mps` | `mumps` | Text |\n| MySQL | None | `mysql` | None |\n| Nginx | Names ending in `.conf` that contain `nginx`, such as `nginx.conf` | `nginx` | Text |\n| NSIS | `.nsh`, `.nsi` | `nsis` | Text |\n| NTriples | `.nt`, `.nq` | `ntriples` | Text |\n| Objective-C | None | `objective-c`, `objc` | None |\n| Objective-C++ | `.mm` | `objective-c++`, `objc++` | Text |\n| OCaml | `.ml`, `.mli`, `.mll`, `.mly` | `ocaml` | Text |\n| Octave | None | `octave` | None |\n| Oz | `.oz` | `oz` | Text |\n| Pascal | `.p`, `.pas` | `pascal` | Text |\n| Perl | `.pl`, `.pm` | `perl` | Text |\n| PGP | `.asc`, `.pgp`, `.sig` | `pgp`, `asciiarmor` | Text |\n| PHP | `.php`, `.php3`, `.php4`, `.php5`, `.php7`, `.phtml` | `php` | Text |\n| Pig | `.pig` | `pig` | Text |\n| Plain text (no highlighting) | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | `text`, `txt`, `plaintext`, `plain`, `none` | Text |\n| PLSQL | `.pls` | `plsql` | Text |\n| PostgreSQL | None | `postgresql` | None |\n| PowerShell | `.ps1`, `.psd1`, `.psm1` | `ps1`, `powershell` | Text |\n| Properties files | `.properties`, `.ini`, `.in` | `ini`, `properties` | Text |\n| ProtoBuf | `.proto` | `protobuf` | Text |\n| Pug | `.pug`, `.jade` | `jade`, `pug` | Text |\n| Puppet | `.pp` | `puppet` | Text |\n| Python | `.build`, `.bzl`, `.py`, `.pyw`, `BUCK`, `BUILD` | `py`, `python` | Text |\n| Q | `.q` | `q` | Text |\n| R | `.r` | `r`, `rscript` | Text |\n| RPM Spec | `.spec` | None | Text |\n| Ruby | `.rb`, `Gemfile`, `Rakefile` | `rb`, `ruby`, `jruby`, `macruby`, `rake`, `rbx` | Text |\n| Rust | `.rs` | `rs`, `rust` | Text |\n| SAS | `.sas` | `sas` | Text |\n| Sass | `.sass` | `sass` | Text |\n| Scala | `.scala` | `scala` | Text |\n| Scheme | `.scm`, `.ss` | `scheme` | Text |\n| SCSS | `.scss` | `scss` | Text |\n| Shell | `.sh`, `.ksh`, `.bash`, `PKGBUILD` | `sh`, `bash`, `zsh`, `shell`, `shellsession`, `console` | Text |\n| Sieve | `.siv`, `.sieve` | `sieve` | Text |\n| Smalltalk | `.st` | `smalltalk` | Text |\n| SML | `.sml`, `.fun`, `.smackspec` | `sml` | Text |\n| Solr | None | `solr` | None |\n| SPARQL | `.rq`, `.sparql` | `sparql`, `sparul` | Text |\n| Spreadsheet | None | `excel`, `formula`, `spreadsheet` | None |\n| SQL | `.sql` | `sql` | Text |\n| SQLite | None | `sqlite` | None |\n| Squirrel | `.nut` | `squirrel` | Text |\n| sTeX | None | `stex` | None |\n| Stylus | `.styl` | `stylus` | Text |\n| SVG (XML highlighting) | `.svg` | `xml`, `rss`, `wsdl`, `xsd` | Image |\n| Swift | `.swift` | `swift` | Text |\n| SystemVerilog | `.v`, `.sv`, `.svh` | `systemverilog` | Text |\n| Tcl | `.tcl` | `tcl` | Text |\n| Textile | `.textile` | `textile` | Text |\n| TiddlyWiki | None | `tiddlywiki` | None |\n| TOML | `.toml` | `toml` | Text |\n| Troff | `.1`, `.2`, `.3`, `.4`, `.5`, `.6`, `.7`, `.8`, `.9` | `troff` | Text |\n| TSX | `.tsx` | `tsx` | Text |\n| TTCN | `.ttcn`, `.ttcn3`, `.ttcnpp` | `ttcn` | Text |\n| TTCN_CFG | `.cfg` | `ttcn_cfg` | Text |\n| Turtle | `.ttl` | `turtle` | Text |\n| TypeScript | `.ts`, `.mts`, `.cts` | `ts`, `typescript` | Text |\n| VB.NET | `.vb` | `vb.net` | Text |\n| VBScript | `.vbs` | `vbscript` | Text |\n| Velocity | `.vtl` | `velocity` | Text |\n| Verilog | None | `verilog` | None |\n| VHDL | `.vhd`, `.vhdl` | `vhdl` | Text |\n| Vue | `.vue` | `vue` | Text |\n| Web IDL | `.webidl` | None | Text |\n| WebAssembly | `.wat`, `.wast` | `webassembly` | Text |\n| XML | `.xml`, `.xsl`, `.xsd` | `xml`, `rss`, `wsdl`, `xsd` | Text |\n| XQuery | `.xy`, `.xquery`, `.xq`, `.xqm`, `.xqy` | `xquery` | Text |\n| X\u00f9 | `.xu` | `x\u00f9` | Text |\n| Yacas | `.ys` | `yacas` | Text |\n| YAML | `.yaml`, `.yml` | `yaml`, `yml` | Text |\n| Z80 | `.z80` | `z80` | Text |\n\n## Related Guides\n\n- [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/)\n- [Edit Markdown](../../view-and-edit-files/edit-markdown/)\n- [Supported File Formats](../supported-file-formats/)\n"}, "page_contents": {"2.0": "+++\ntitle = \"Text File Support and Syntax Highlighting\"\n+++\n\nUse this reference to check which files open in the text editor and which language labels you can use in Markdown code blocks. Sambee uses the same syntax highlighting for the text editor, Markdown source, and code blocks in Markdown previews.\n\n## Text File Support\n\nFiles with an extension or special filename listed below open in the text editor by default, with two exceptions: `.md` and `.markdown` open in the Markdown viewer, and `.svg` opens in the image viewer. A saved viewer preference or the file's MIME type can override the filename-based choice.\n\nThe filename also selects the highlighting language:\n\n- Special filenames take priority over extensions. Their case rules vary: `Dockerfile` requires that spelling, while `nginx.conf` matches in any case.\n- Extensions aren't case-sensitive. Only the final suffix counts, so `project.cmake.in` uses Properties highlighting through `.in`, not CMake.\n- Shared extensions select one language: `.m` uses Mathematica, `.sig` uses PGP, and `.v` uses SystemVerilog.\n\nPlain-text formats such as `.txt` and `.log` open in the text editor without highlighting. Unmatched files don't automatically open as text, but you can choose the text editor from the viewer picker; without a language match, they use plain text.\n\nFor images, PDFs, archives, and other supported formats, see [Supported File Formats](../supported-file-formats/).\n\n## Markdown Code Block Languages\n\nPut a language label immediately after the opening three backticks. For example, `py` selects Python:\n\n````markdown\n```py\ndef greet(name):\n\treturn f\"Hello, {name}!\"\n```\n````\n\nLabels aren't case-sensitive. Labels on the same table row are interchangeable, so `python` works just like `py`. Sambee reads only the first whitespace-separated word after the opening fence; a language's full name works only if it's listed as a label.\n\nUnlabelled blocks and unknown labels use plain text. To request plain text explicitly, use `text`, `txt`, `plaintext`, `plain`, or `none`. Very large code blocks can also remain plain text without losing their contents.\n\n## File and Language Reference\n\nUse the file column to look up a file and the Markdown column to choose a code block label. **None** in the file or viewer column means the language is available only in Markdown code blocks. **None** in the Markdown column means there's no accepted code block label for that format. Viewer choices assume no MIME-type or saved-preference override.\n\n| Language or format | File extensions or names | Markdown labels | Default viewer |\n|---|---|---|---|\n| APL | `.dyalog`, `.apl` | `apl` | Text |\n| ASN.1 | `.asn`, `.asn1` | `asn.1` | Text |\n| Asterisk | `extensions.conf` | `asterisk` | Text |\n| Brainfuck | `.b`, `.bf` | `brainfuck` | Text |\n| C | `.c`, `.h`, `.ino` | `c` | Text |\n| C# | `.cs` | `cs`, `csharp`, `c#` | Text |\n| C++ | `.cpp`, `.c++`, `.cc`, `.cxx`, `.hpp`, `.h++`, `.hh`, `.hxx` | `cpp`, `c++` | Text |\n| Clojure | `.clj`, `.cljc`, `.cljx` | `clojure` | Text |\n| ClojureScript | `.cljs` | `clojurescript` | Text |\n| Closure Stylesheets (GSS) | `.gss` | None | Text |\n| CMake | `.cmake`, `CMakeLists.txt` | `cmake` | Text |\n| COBOL | `.cob`, `.cpy` | `cobol` | Text |\n| CoffeeScript | `.coffee` | `coffee`, `coffee-script`, `coffeescript` | Text |\n| Common Lisp | `.cl`, `.lisp`, `.el` | `lisp` | Text |\n| CQL (Cassandra) | `.cql` | `cql`, `cassandra` | Text |\n| Crystal | `.cr` | `crystal` | Text |\n| CSS | `.css` | `css` | Text |\n| Cypher | `.cyp`, `.cypher` | `cypher` | Text |\n| Cython | `.pyx`, `.pxd`, `.pxi` | `cython` | Text |\n| D | `.d` | `d` | Text |\n| Dart | `.dart` | `dart` | Text |\n| Diff | `.diff`, `.patch` | `diff` | Text |\n| Dockerfile | `Dockerfile` | `docker`, `dockerfile` | Text |\n| DTD | `.dtd` | `dtd` | Text |\n| Dylan | `.dylan`, `.dyl`, `.intr` | `dylan` | Text |\n| EBNF | None | `ebnf` | None |\n| ECL | `.ecl` | `ecl` | Text |\n| edn | `.edn` | `edn` | Text |\n| Eiffel | `.e` | `eiffel` | Text |\n| Elm | `.elm` | `elm` | Text |\n| Erlang | `.erl` | `erlang` | Text |\n| Esper | None | `esper` | None |\n| F# | `.fs` | `fsharp`, `f#` | Text |\n| Factor | `.factor` | `factor` | Text |\n| FCL | None | `fcl` | None |\n| Forth | `.forth`, `.fth`, `.4th` | `forth` | Text |\n| Fortran | `.f`, `.for`, `.f77`, `.f90`, `.f95` | `fortran` | Text |\n| Gas (GNU assembler) | `.s` | `gas` | Text |\n| Gherkin | `.feature` | `gherkin` | Text |\n| Go | `.go` | `go` | Text |\n| Groovy | `.groovy`, `.gradle`, `Jenkinsfile` | `groovy` | Text |\n| Haskell | `.hs` | `haskell` | Text |\n| Haxe | `.hx` | `haxe` | Text |\n| HTML | `.html`, `.htm`, `.handlebars`, `.hbs` | `html`, `htm`, `xhtml` | Text |\n| HTTP | None | `http` | None |\n| HXML | `.hxml` | `hxml` | Text |\n| IDL | `.pro` | `idl` | Text |\n| Java | `.java` | `java` | Text |\n| JavaScript | `.js`, `.mjs`, `.cjs` | `js`, `javascript`, `ecmascript`, `node` | Text |\n| Jinja | `.j2`, `.jinja`, `.jinja2` | `jinja` | Text |\n| JSON | `.json`, `.map` | `json`, `json5` | Text |\n| JSON-LD | `.jsonld` | `jsonld`, `json-ld` | Text |\n| JSX | `.jsx` | `jsx` | Text |\n| Julia | `.jl` | `julia` | Text |\n| Kotlin | `.kt`, `.kts` | `kt`, `kotlin` | Text |\n| LaTeX | `.text`, `.ltx`, `.tex` | `tex`, `latex` | Text |\n| LESS | `.less` | `less` | Text |\n| Liquid | `.liquid` | `liquid` | Text |\n| LiveScript | `.ls` | `ls`, `livescript` | Text |\n| Lua | `.lua` | `lua` | Text |\n| MariaDB SQL | None | `mariadb` | None |\n| Markdown | `.md`, `.markdown` | `md`, `markdown` | Markdown |\n| Markdown source | `.mkd` | `md`, `markdown` | Text |\n| Mathematica | `.m`, `.nb`, `.wl`, `.wls` | `mathematica` | Text |\n| Mbox | `.mbox` | `mbox` | Text |\n| mIRC | `.mrc` | `mirc` | Text |\n| Modelica | `.mo` | `modelica` | Text |\n| MS SQL | None | `mssql` | None |\n| MscGen | `.mscgen`, `.mscin`, `.msc` | `mscgen` | Text |\n| MsGenny | `.msgenny` | `msgenny` | Text |\n| MUMPS | `.mps` | `mumps` | Text |\n| MySQL | None | `mysql` | None |\n| Nginx | Names ending in `.conf` that contain `nginx`, such as `nginx.conf` | `nginx` | Text |\n| NSIS | `.nsh`, `.nsi` | `nsis` | Text |\n| NTriples | `.nt`, `.nq` | `ntriples` | Text |\n| Objective-C | None | `objective-c`, `objc` | None |\n| Objective-C++ | `.mm` | `objective-c++`, `objc++` | Text |\n| OCaml | `.ml`, `.mli`, `.mll`, `.mly` | `ocaml` | Text |\n| Octave | None | `octave` | None |\n| Oz | `.oz` | `oz` | Text |\n| Pascal | `.p`, `.pas` | `pascal` | Text |\n| Perl | `.pl`, `.pm` | `perl` | Text |\n| PGP | `.asc`, `.pgp`, `.sig` | `pgp`, `asciiarmor` | Text |\n| PHP | `.php`, `.php3`, `.php4`, `.php5`, `.php7`, `.phtml` | `php` | Text |\n| Pig | `.pig` | `pig` | Text |\n| Plain text (no highlighting) | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | `text`, `txt`, `plaintext`, `plain`, `none` | Text |\n| PLSQL | `.pls` | `plsql` | Text |\n| PostgreSQL | None | `postgresql` | None |\n| PowerShell | `.ps1`, `.psd1`, `.psm1` | `ps1`, `powershell` | Text |\n| Properties files | `.properties`, `.ini`, `.in` | `ini`, `properties` | Text |\n| ProtoBuf | `.proto` | `protobuf` | Text |\n| Pug | `.pug`, `.jade` | `jade`, `pug` | Text |\n| Puppet | `.pp` | `puppet` | Text |\n| Python | `.build`, `.bzl`, `.py`, `.pyw`, `BUCK`, `BUILD` | `py`, `python` | Text |\n| Q | `.q` | `q` | Text |\n| R | `.r` | `r`, `rscript` | Text |\n| RPM Spec | `.spec` | None | Text |\n| Ruby | `.rb`, `Gemfile`, `Rakefile` | `rb`, `ruby`, `jruby`, `macruby`, `rake`, `rbx` | Text |\n| Rust | `.rs` | `rs`, `rust` | Text |\n| SAS | `.sas` | `sas` | Text |\n| Sass | `.sass` | `sass` | Text |\n| Scala | `.scala` | `scala` | Text |\n| Scheme | `.scm`, `.ss` | `scheme` | Text |\n| SCSS | `.scss` | `scss` | Text |\n| Shell | `.sh`, `.ksh`, `.bash`, `PKGBUILD` | `sh`, `bash`, `zsh`, `shell`, `shellsession`, `console` | Text |\n| Sieve | `.siv`, `.sieve` | `sieve` | Text |\n| Smalltalk | `.st` | `smalltalk` | Text |\n| SML | `.sml`, `.fun`, `.smackspec` | `sml` | Text |\n| Solr | None | `solr` | None |\n| SPARQL | `.rq`, `.sparql` | `sparql`, `sparul` | Text |\n| Spreadsheet | None | `excel`, `formula`, `spreadsheet` | None |\n| SQL | `.sql` | `sql` | Text |\n| SQLite | None | `sqlite` | None |\n| Squirrel | `.nut` | `squirrel` | Text |\n| sTeX | None | `stex` | None |\n| Stylus | `.styl` | `stylus` | Text |\n| SVG (XML highlighting) | `.svg` | `xml`, `rss`, `wsdl`, `xsd` | Image |\n| Swift | `.swift` | `swift` | Text |\n| SystemVerilog | `.v`, `.sv`, `.svh` | `systemverilog` | Text |\n| Tcl | `.tcl` | `tcl` | Text |\n| Textile | `.textile` | `textile` | Text |\n| TiddlyWiki | None | `tiddlywiki` | None |\n| TOML | `.toml` | `toml` | Text |\n| Troff | `.1`, `.2`, `.3`, `.4`, `.5`, `.6`, `.7`, `.8`, `.9` | `troff` | Text |\n| TSX | `.tsx` | `tsx` | Text |\n| TTCN | `.ttcn`, `.ttcn3`, `.ttcnpp` | `ttcn` | Text |\n| TTCN_CFG | `.cfg` | `ttcn_cfg` | Text |\n| Turtle | `.ttl` | `turtle` | Text |\n| TypeScript | `.ts`, `.mts`, `.cts` | `ts`, `typescript` | Text |\n| VB.NET | `.vb` | `vb.net` | Text |\n| VBScript | `.vbs` | `vbscript` | Text |\n| Velocity | `.vtl` | `velocity` | Text |\n| Verilog | None | `verilog` | None |\n| VHDL | `.vhd`, `.vhdl` | `vhdl` | Text |\n| Vue | `.vue` | `vue` | Text |\n| Web IDL | `.webidl` | None | Text |\n| WebAssembly | `.wat`, `.wast` | `webassembly` | Text |\n| XML | `.xml`, `.xsl`, `.xsd` | `xml`, `rss`, `wsdl`, `xsd` | Text |\n| XQuery | `.xy`, `.xquery`, `.xq`, `.xqm`, `.xqy` | `xquery` | Text |\n| X\u00f9 | `.xu` | `x\u00f9` | Text |\n| Yacas | `.ys` | `yacas` | Text |\n| YAML | `.yaml`, `.yml` | `yaml`, `yml` | Text |\n| Z80 | `.z80` | `z80` | Text |\n\n## Related Guides\n\n- [View and Edit Text Files](../../view-and-edit-files/view-and-edit-text-files/)\n- [Edit Markdown](../../view-and-edit-files/edit-markdown/)\n- [Supported File Formats](../supported-file-formats/)\n"}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/account-and-preferences", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "account-and-preferences", "title": "Account and Preferences", "path": "user-guide/account-and-preferences", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/account-and-preferences/manage-your-account", "parent_id": "section:user-guide/account-and-preferences", "depth": 2, "kind": "page", "label": "manage-your-account", "title": "Manage Your Account", "path": "user-guide/account-and-preferences/manage-your-account", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 10, "diff_removed": 0}}, "content_versions": {"0.9": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "1.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "2.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign In With A Local Password\n\nUsernames aren't case-sensitive: `Testuser` and `testuser` sign in to the same account. Leading and trailing username whitespace is ignored. Passwords remain case-sensitive and aren't trimmed.\n\nIf an older installation already contains accounts whose usernames differ only by case, those accounts temporarily require their exact username spelling. Ask an administrator to resolve the conflicting names. Once the conflict is resolved, capitalization no longer matters.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\nAfter you sign out, your next sign-in in that tab opens the main file browser. Sambee does not save that tab's previous page for the next sign-in.\n\nIf an OIDC session expires or is revoked, signing in again returns affected tabs to their previous pages. Other open tabs recover automatically, or when you bring them into view.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "1.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "2.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign In With A Local Password\n\nUsernames aren't case-sensitive: `Testuser` and `testuser` sign in to the same account. Leading and trailing username whitespace is ignored. Passwords remain case-sensitive and aren't trimmed.\n\nIf an older installation already contains accounts whose usernames differ only by case, those accounts temporarily require their exact username spelling. Ask an administrator to resolve the conflicting names. Once the conflict is resolved, capitalization no longer matters.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\nAfter you sign out, your next sign-in in that tab opens the main file browser. Sambee does not save that tab's previous page for the next sign-in.\n\nIf an OIDC session expires or is revoked, signing in again returns affected tabs to their previous pages. Other open tabs recover automatically, or when you bring them into view.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. Sambee signs out this browser after a successful password change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\n**Sessions** separates **This browser** from **Other sessions**. Password sign-in has no server-side browser-session list; other sessions are OIDC browser sessions.\n\nOIDC sessions show their creation and last-active times. Browser labels such as **Firefox on Linux** help you distinguish sessions, but do not uniquely identify a device. Older sessions may have no label.\n\nUse **Revoke** to end another OIDC browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/account-and-preferences/file-browser-preferences", "parent_id": "section:user-guide/account-and-preferences", "depth": 2, "kind": "page", "label": "file-browser-preferences", "title": "File Browser Preferences", "path": "user-guide/account-and-preferences/file-browser-preferences", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"1.0": "+++\ntitle = \"File Browser Preferences\"\n+++\n\nThese **Settings \u003e File Browser** options apply to your browser preferences, not server policy.\n\n## File Selection\n\n**Automatic** enables touch selection on larger devices with a coarse primary pointer, such as a tablet. **Always on** enables it on all larger layouts; **Off** disables it there. Phone layouts always provide touch selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\n## Shortcut Hints\n\n**Auto** shows hints on larger layouts and after keyboard use in the current compact-layout session. **Always** shows them in all layouts; **Never** hides shortcut labels without hiding Quick Bar status.\n\n## Clear Personal History\n\nClear file history under **File Search** or directory history under **Directory Navigation**. This removes history records, not files or folders. History is private to your account. Server retention and exclusions are [administrator policy](../../../admin-guide/reference/configuration-file-reference/#file-search-and-history-policy).\n", "2.0": "+++\ntitle = \"File Browser Preferences\"\n+++\n\nThese **Settings \u003e File Browser** options apply to your browser preferences, not server policy.\n\n## File Selection\n\n**Automatic** enables touch selection on larger devices with a coarse primary pointer, such as a tablet. **Always on** enables it on all larger layouts; **Off** disables it there. Phone layouts always provide touch selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\n## Shortcut Hints\n\n**Auto** shows hints on larger layouts and after keyboard use in the current compact-layout session. **Always** shows them in all layouts; **Never** hides shortcut labels without hiding Quick Bar status.\n\n## Clear Personal History\n\nClear file history under **File Search** or directory history under **Directory Navigation**. This removes history records, not files or folders. History is private to your account. Server retention and exclusions are [administrator policy](../../../admin-guide/reference/configuration-file-reference/#file-search-and-history-policy).\n"}, "page_contents": {"1.0": "+++\ntitle = \"File Browser Preferences\"\n+++\n\nThese **Settings \u003e File Browser** options apply to your browser preferences, not server policy.\n\n## File Selection\n\n**Automatic** enables touch selection on larger devices with a coarse primary pointer, such as a tablet. **Always on** enables it on all larger layouts; **Off** disables it there. Phone layouts always provide touch selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\n## Shortcut Hints\n\n**Auto** shows hints on larger layouts and after keyboard use in the current compact-layout session. **Always** shows them in all layouts; **Never** hides shortcut labels without hiding Quick Bar status.\n\n## Clear Personal History\n\nClear file history under **File Search** or directory history under **Directory Navigation**. This removes history records, not files or folders. History is private to your account. Server retention and exclusions are [administrator policy](../../../admin-guide/reference/configuration-file-reference/#file-search-and-history-policy).\n", "2.0": "+++\ntitle = \"File Browser Preferences\"\n+++\n\nThese **Settings \u003e File Browser** options apply to your browser preferences, not server policy.\n\n## File Selection\n\n**Automatic** enables touch selection on larger devices with a coarse primary pointer, such as a tablet. **Always on** enables it on all larger layouts; **Off** disables it there. Phone layouts always provide touch selection. See [Select Files and Folders](../../find-and-browse-files/select-files-and-folders/).\n\n## Shortcut Hints\n\n**Auto** shows hints on larger layouts and after keyboard use in the current compact-layout session. **Always** shows them in all layouts; **Never** hides shortcut labels without hiding Quick Bar status.\n\n## Clear Personal History\n\nClear file history under **File Search** or directory history under **Directory Navigation**. This removes history records, not files or folders. History is private to your account. Server retention and exclusions are [administrator policy](../../../admin-guide/reference/configuration-file-reference/#file-search-and-history-policy).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:admin-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "admin-guide", "title": "Admin Guide", "path": "admin-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 1, "diff_removed": 3}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Configuration](./configuration/configuration-key-reference/): Review the config keys admins most often change and follow the related path and persistence references.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.8": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Configuration](./configuration/configuration-key-reference/): Review the config keys admins most often change and follow the related path and persistence references.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.9": "+++\ntitle = \"Admin Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "1.0": "+++\ntitle = \"Admin Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "2.0": "+++\ntitle = \"Admin Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/overview-and-planning", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "overview-and-planning", "title": "Overview and Planning", "path": "admin-guide/overview-and-planning", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/overview-and-planning/architecture-overview", "parent_id": "section:admin-guide/overview-and-planning", "depth": 2, "kind": "page", "label": "architecture-overview", "title": "Architecture Overview", "path": "admin-guide/overview-and-planning/architecture-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.8": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.9": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "1.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "2.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.8": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.9": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "1.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "2.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/installation-and-deployment", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "installation-and-deployment", "title": "Installation and Deployment", "path": "admin-guide/installation-and-deployment", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/installation-and-deployment/deploy-sambee-with-docker", "parent_id": "section:admin-guide/installation-and-deployment", "depth": 2, "kind": "page", "label": "deploy-sambee-with-docker", "title": "Deploy Sambee With Docker", "path": "admin-guide/installation-and-deployment/deploy-sambee-with-docker", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 1, "diff_removed": 8}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 1, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.8": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.9": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "1.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "2.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/sambee-app/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.8": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.9": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "1.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "2.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/sambee-app/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/installation-and-deployment/first-startup-and-first-admin-login", "parent_id": "section:admin-guide/installation-and-deployment", "depth": 2, "kind": "page", "label": "first-startup-and-first-admin-login", "title": "First Startup And First Admin Login", "path": "admin-guide/installation-and-deployment/first-startup-and-first-admin-login", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.8": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.9": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "1.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "2.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n"}, "page_contents": {"0.7": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.8": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.9": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "1.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "2.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/network-and-reverse-proxy", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "network-and-reverse-proxy", "title": "Network and Reverse Proxy", "path": "admin-guide/network-and-reverse-proxy", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy", "parent_id": "section:admin-guide/network-and-reverse-proxy", "depth": 2, "kind": "page", "label": "put-sambee-behind-a-reverse-proxy", "title": "Put Sambee Behind A Reverse Proxy", "path": "admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.8": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.9": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "1.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "2.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.8": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.9": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "1.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "2.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/network-and-reverse-proxy/network-settings", "parent_id": "section:admin-guide/network-and-reverse-proxy", "depth": 2, "kind": "page", "label": "network-settings", "title": "Network Settings", "path": "admin-guide/network-and-reverse-proxy/network-settings", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "1.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "2.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "1.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "2.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/configuration", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "configuration", "title": "Configuration", "path": "admin-guide/configuration", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/configuration/configuration-key-reference", "parent_id": "section:admin-guide/configuration", "depth": 2, "kind": "page", "label": "configuration-key-reference", "title": "Configuration Key Reference", "path": "admin-guide/configuration/configuration-key-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {"0.7": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "0.8": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "0.8": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/operations-and-maintenance", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "operations-and-maintenance", "title": "Operations and Maintenance", "path": "admin-guide/operations-and-maintenance", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/view-logs-and-restart-services", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "view-logs-and-restart-services", "title": "View Logs And Restart Services", "path": "admin-guide/operations-and-maintenance/view-logs-and-restart-services", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.8": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.9": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "1.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "2.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n"}, "page_contents": {"0.7": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.8": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.9": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "1.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "2.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/update-sambee-safely", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "update-sambee-safely", "title": "Update Sambee Safely", "path": "admin-guide/operations-and-maintenance/update-sambee-safely", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 24, "diff_removed": 0}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.8": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.9": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "1.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.", "2.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding."}, "page_contents": {"0.7": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.8": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.9": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "1.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.", "2.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/backup-and-restore-planning", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "backup-and-restore-planning", "title": "Backup And Restore Planning", "path": "admin-guide/operations-and-maintenance/backup-and-restore-planning", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.8": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.9": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "1.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "2.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.8": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.9": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "1.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "2.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/manage-directory-search", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "manage-directory-search", "title": "Manage Directory Search", "path": "admin-guide/operations-and-maintenance/manage-directory-search", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "authored"}}, "content_versions": {"2.0": "+++\ntitle = \"Manage Directory Search\"\n+++\n\nUse **Admin \u003e Directory Search** to set resource limits for backend and Companion directory indexes. Backend changes take effect on live sources. Paired browsers deliver saved Companion policy automatically while an authenticated session is active.\n\n## Resource Controls\n\nThe settings include storage, retention, cache, and verification controls, with help and allowed ranges beside each field. Start with the defaults and adjust them for the server or device capacity.\n\nThe disk budget and cache target are not hard disk or process-memory limits. Leave extra free space for background work. Lowering the budget can pause index growth; it does not trim active indexes.\n\n## Companion Policy Delivery\n\nPairing authorizes settings delivery. The most recently paired server manages Companion settings. Pairing that server again also selects it as authority. Other paired servers keep their file-access pairing but cannot replace managed settings.\n\nAll active, authenticated users can deliver the saved canonical policy. Only administrators can edit it. There is no separate policy approval or Apply action.\n\n**Settings \u003e Local Drives** shows the settings authority and separate synchronization states for directory policy, theme, and localization. Checks run after pairing, login, reconnect, persisted changes, and periodically while a tab is visible. A theme or localization change does not revise or reapply unchanged directory policy.\n\nThe device must reach the Sambee backend directly over HTTPS with a valid certificate. Redirects are not supported. HTTP is allowed only for loopback development origins.\n\n## Troubleshooting\n\nIf delivery fails, Companion keeps the last valid value for each section, or built-in defaults before the first delivery. Directory search remains available. Follow the displayed recovery action and use **Retry**. Update both applications when status reports an incompatible settings protocol.\n\nTo change authority, pair the intended server again. Unpairing the authoritative origin clears authority and keeps the last valid settings; Companion does not select another paired server automatically. For older installations with several pairings and no usable policy binding, pair the intended server again to establish authority.\n\nIf index growth pauses, restore free disk space or increase the relevant disk budget.\n\nIndexes are reused after a restart. Retained results remain unverified until background verification completes. A temporary disconnection keeps the index; restore source access to resume work.\n\n### SMB Verification and Recovery\n\nThe backend waits up to 10 seconds for directory notifications before its first source check and scan. If notification setup fails or times out, verification starts without monitoring and watcher retries continue. If monitoring becomes ready later, verification safely retries reads made before that transition. No cache reset is needed.\n\nRetained results become searchable after a valid source-root check, even while full verification continues. An unavailable root temporarily blocks search without deleting the index. Restore the source connection or permissions and let background recovery continue.\n\nDirectory changes normally retry only affected parents. Completed quiet branches remain available, and background work gives both existing results and full verification time to progress. A parent that changes during its read is deferred for at least one second. A full pass may remain incomplete while directories keep changing. To confirm complete coverage, allow a quiet period and check the verification time.\n\nA denied folder, unsafe directory, or unsupported name does not stop verification of readable folders. A completed pass can have partial coverage and a verification time. It does not mean that every folder was read. Failed folders are checked at the next regular verification. Restore their permissions or correct unsupported names to improve coverage. A failed incremental read keeps stored descendants until a later check can confirm a change.\n\nStatus messages show active conditions. A local retry alone does not mean that the source is unavailable. Follow a displayed storage, access, or monitoring recovery action. Retry delays account for both scan gates and watcher retries; a longer failure backoff can delay scan work beyond the one-second change retry. Repeated searches and status checks do not shorten that delay.\n\n### Source Boundaries\n\nSMB indexing stays within the configured share and folder. Storage mounted inside that share is included unless it is exposed through a redirect or reparse point. Local indexing does not cross mount boundaries.\n\nLocal fixed drives use a separate index when the volume serial or file-system UUID changes. Removable and unknown drives also start a new generation when the volume label, file-system type, or total capacity changes. Each volume at the same path can reuse its own retained index. Missing media pauses search without deleting the index. On Linux, mount the volume again; the empty mount-point folder is not a replacement source.\n\nFor supported platforms and database precautions, see [Directory-Search Databases](../../reference/companion-support-reference/#directory-search-databases). For backend storage configuration, see [Configuration File Reference](../../reference/configuration-file-reference/#directory-index-policy).\n"}, "page_contents": {"2.0": "+++\ntitle = \"Manage Directory Search\"\n+++\n\nUse **Admin \u003e Directory Search** to set resource limits for backend and Companion directory indexes. Backend changes take effect on live sources. Paired browsers deliver saved Companion policy automatically while an authenticated session is active.\n\n## Resource Controls\n\nThe settings include storage, retention, cache, and verification controls, with help and allowed ranges beside each field. Start with the defaults and adjust them for the server or device capacity.\n\nThe disk budget and cache target are not hard disk or process-memory limits. Leave extra free space for background work. Lowering the budget can pause index growth; it does not trim active indexes.\n\n## Companion Policy Delivery\n\nPairing authorizes settings delivery. The most recently paired server manages Companion settings. Pairing that server again also selects it as authority. Other paired servers keep their file-access pairing but cannot replace managed settings.\n\nAll active, authenticated users can deliver the saved canonical policy. Only administrators can edit it. There is no separate policy approval or Apply action.\n\n**Settings \u003e Local Drives** shows the settings authority and separate synchronization states for directory policy, theme, and localization. Checks run after pairing, login, reconnect, persisted changes, and periodically while a tab is visible. A theme or localization change does not revise or reapply unchanged directory policy.\n\nThe device must reach the Sambee backend directly over HTTPS with a valid certificate. Redirects are not supported. HTTP is allowed only for loopback development origins.\n\n## Troubleshooting\n\nIf delivery fails, Companion keeps the last valid value for each section, or built-in defaults before the first delivery. Directory search remains available. Follow the displayed recovery action and use **Retry**. Update both applications when status reports an incompatible settings protocol.\n\nTo change authority, pair the intended server again. Unpairing the authoritative origin clears authority and keeps the last valid settings; Companion does not select another paired server automatically. For older installations with several pairings and no usable policy binding, pair the intended server again to establish authority.\n\nIf index growth pauses, restore free disk space or increase the relevant disk budget.\n\nIndexes are reused after a restart. Retained results remain unverified until background verification completes. A temporary disconnection keeps the index; restore source access to resume work.\n\n### SMB Verification and Recovery\n\nThe backend waits up to 10 seconds for directory notifications before its first source check and scan. If notification setup fails or times out, verification starts without monitoring and watcher retries continue. If monitoring becomes ready later, verification safely retries reads made before that transition. No cache reset is needed.\n\nRetained results become searchable after a valid source-root check, even while full verification continues. An unavailable root temporarily blocks search without deleting the index. Restore the source connection or permissions and let background recovery continue.\n\nDirectory changes normally retry only affected parents. Completed quiet branches remain available, and background work gives both existing results and full verification time to progress. A parent that changes during its read is deferred for at least one second. A full pass may remain incomplete while directories keep changing. To confirm complete coverage, allow a quiet period and check the verification time.\n\nA denied folder, unsafe directory, or unsupported name does not stop verification of readable folders. A completed pass can have partial coverage and a verification time. It does not mean that every folder was read. Failed folders are checked at the next regular verification. Restore their permissions or correct unsupported names to improve coverage. A failed incremental read keeps stored descendants until a later check can confirm a change.\n\nStatus messages show active conditions. A local retry alone does not mean that the source is unavailable. Follow a displayed storage, access, or monitoring recovery action. Retry delays account for both scan gates and watcher retries; a longer failure backoff can delay scan work beyond the one-second change retry. Repeated searches and status checks do not shorten that delay.\n\n### Source Boundaries\n\nSMB indexing stays within the configured share and folder. Storage mounted inside that share is included unless it is exposed through a redirect or reparse point. Local indexing does not cross mount boundaries.\n\nLocal fixed drives use a separate index when the volume serial or file-system UUID changes. Removable and unknown drives also start a new generation when the volume label, file-system type, or total capacity changes. Each volume at the same path can reuse its own retained index. Missing media pauses search without deleting the index. On Linux, mount the volume again; the empty mount-point folder is not a replacement source.\n\nFor supported platforms and database precautions, see [Directory-Search Databases](../../reference/companion-support-reference/#directory-search-databases). For backend storage configuration, see [Configuration File Reference](../../reference/configuration-file-reference/#directory-index-policy).\n"}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/reference", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "reference", "title": "Reference", "path": "admin-guide/reference", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/reference/port-and-path-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "port-and-path-reference", "title": "Port And Path Reference", "path": "admin-guide/reference/port-and-path-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.8": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.9": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "1.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "2.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.8": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.9": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "1.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "2.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/companion-support-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "companion-support-reference", "title": "Companion Support Reference", "path": "admin-guide/reference/companion-support-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 13, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.8": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.9": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "1.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "2.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Directory-Search Databases\n\nCompanion stores its SQLite directory indexes in the current OS user's cache directory.\n\n| Platform | Location |\n|---|---|\n| Linux | `$XDG_CACHE_HOME/app.sambee.companion/directory-index/sqlite/`, or `~/.cache/app.sambee.companion/directory-index/sqlite/` when `XDG_CACHE_HOME` is not set to an absolute path |\n| Windows | `%LOCALAPPDATA%\\app.sambee.companion\\directory-index\\sqlite\\` |\n\nThese databases contain local directory paths. Keep access restricted to the device's OS user, and exit Companion before copying or removing index files. Do not edit the databases or remove individual SQLite sidecar files. macOS directory indexing is not available.\n\nSee [Manage Directory Search](../../operations-and-maintenance/manage-directory-search/) to configure resource limits and apply them to devices.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.8": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.9": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "1.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "2.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Directory-Search Databases\n\nCompanion stores its SQLite directory indexes in the current OS user's cache directory.\n\n| Platform | Location |\n|---|---|\n| Linux | `$XDG_CACHE_HOME/app.sambee.companion/directory-index/sqlite/`, or `~/.cache/app.sambee.companion/directory-index/sqlite/` when `XDG_CACHE_HOME` is not set to an absolute path |\n| Windows | `%LOCALAPPDATA%\\app.sambee.companion\\directory-index\\sqlite\\` |\n\nThese databases contain local directory paths. Keep access restricted to the device's OS user, and exit Companion before copying or removing index files. Do not edit the databases or remove individual SQLite sidecar files. macOS directory indexing is not available.\n\nSee [Manage Directory Search](../../operations-and-maintenance/manage-directory-search/) to configure resource limits and apply them to devices.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/configuration-file-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "configuration-file-reference", "title": "Configuration File Reference", "path": "admin-guide/reference/configuration-file-reference", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 8, "diff_removed": 0}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 12, "diff_removed": 4}}, "content_versions": {"0.9": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "1.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## File Search and History Policy\n\nUse **Settings \u003e File Search** for shared retention, results per group, and file-history exclusions. These are administrator settings, not personal File Browser preferences. The page identifies built-in defaults or a saved system override; administrators can reset an override.\n\nLowering retention removes the oldest history records immediately. Zero clears history and prevents new records. Image, temporary, backup, and extension exclusions apply before file history is stored. Enter one literal extension per exclusion; Sambee normalizes `TMP` to `.tmp`.\n\nUsers can clear their own file and directory histories in **Settings \u003e File Browser**. Removing history does not delete stored files or folders.\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "2.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location` | Selects the private backend directory-index root. SQLite catalogues are reused after restart and marked unverified until background verification completes. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## File Search and History Policy\n\nUse **Settings \u003e File Search** for shared retention, results per group, and file-history exclusions. These are administrator settings, not personal File Browser preferences.\n\n**Recent files and directories to retain** defaults to 200 files and 200 directories per user, with separate limits for the lists. Existing administrator overrides remain unchanged. Lowering retention immediately removes the oldest records from both lists; zero clears both lists and prevents new records. **Results per group** defaults to 10 and applies to both search modes.\n\nImage, temporary, backup, and extension exclusions apply only to file history before storage. Enter one literal extension per exclusion; Sambee normalizes `TMP` to `.tmp`.\n\nUsers can clear their own histories in **Settings \u003e File Browser**. Removing history does not delete stored files or folders.\n\n## Directory-Index Policy\n\nDirectory-index resource policies have no TOML override. Configure them in **Admin \u003e Directory Search**; see [Manage Directory Search](../../operations-and-maintenance/manage-directory-search/) for controls, Companion approval, and recovery.\n\n`directory_cache.location` selects only the backend storage root.\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "1.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## File Search and History Policy\n\nUse **Settings \u003e File Search** for shared retention, results per group, and file-history exclusions. These are administrator settings, not personal File Browser preferences. The page identifies built-in defaults or a saved system override; administrators can reset an override.\n\nLowering retention removes the oldest history records immediately. Zero clears history and prevents new records. Image, temporary, backup, and extension exclusions apply before file history is stored. Enter one literal extension per exclusion; Sambee normalizes `TMP` to `.tmp`.\n\nUsers can clear their own file and directory histories in **Settings \u003e File Browser**. Removing history does not delete stored files or folders.\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "2.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location` | Selects the private backend directory-index root. SQLite catalogues are reused after restart and marked unverified until background verification completes. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## File Search and History Policy\n\nUse **Settings \u003e File Search** for shared retention, results per group, and file-history exclusions. These are administrator settings, not personal File Browser preferences.\n\n**Recent files and directories to retain** defaults to 200 files and 200 directories per user, with separate limits for the lists. Existing administrator overrides remain unchanged. Lowering retention immediately removes the oldest records from both lists; zero clears both lists and prevents new records. **Results per group** defaults to 10 and applies to both search modes.\n\nImage, temporary, backup, and extension exclusions apply only to file history before storage. Enter one literal extension per exclusion; Sambee normalizes `TMP` to `.tmp`.\n\nUsers can clear their own histories in **Settings \u003e File Browser**. Removing history does not delete stored files or folders.\n\n## Directory-Index Policy\n\nDirectory-index resource policies have no TOML override. Configure them in **Admin \u003e Directory Search**; see [Manage Directory Search](../../operations-and-maintenance/manage-directory-search/) for controls, Companion approval, and recovery.\n\n`directory_cache.location` selects only the backend storage root.\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/smb-settings", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "smb-settings", "title": "Smb Settings", "path": "admin-guide/reference/smb-settings", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "1.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "2.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "1.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "2.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/authentication", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "authentication", "title": "Authentication", "path": "admin-guide/authentication", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/authentication/authentication-overview", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "authentication-overview", "title": "Authentication Overview", "path": "admin-guide/authentication/authentication-overview", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "1.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "2.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "1.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "2.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/password-authentication", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "password-authentication", "title": "Password Authentication", "path": "admin-guide/authentication/password-authentication", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "1.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "2.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "1.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "2.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/openid-connect-authentication-setup", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "openid-connect-authentication-setup", "title": "Openid Connect Authentication Setup", "path": "admin-guide/authentication/openid-connect-authentication-setup", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 23, "diff_removed": 7}}, "content_versions": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- Scopes:\n   - `openid`: required\n   - `profile`: often necessary for the provider to return `preferred_username`, which Sambee requires\n   - `email`: optional\n   - `groups`: required when using group admission or group-based role mappings\n   - `offline_access`: may be required for refresh tokens, depending on the provider\n- Authorization code grant\n- Refresh token grant: optional\n\n#### Token Lifetimes\n\nConfigure token lifetimes:\n\n- Refresh token, if the provider issues one:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n#### Refresh Tokens\n\nHaving the provider issue refresh tokens is recommended as that enables background session renewal without user interaction.\n\nProviders that don't issue refresh tokens can still be used with Sambee. They must return an ID token with a valid `auth_time` claim when Sambee requests `max_age`.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid` and every scope required for the configured claims, such as `profile` and `email`. Add `groups` for group admission or group-based role mappings. Add `offline_access` only if supported and needed for provider refresh tokens. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control the maximum age of a verified IdP sign-in. The default is 30 days.\n\nSet **Session limit without refresh token (hours)** separately for sign-ins that return no refresh token (default 8 hours; allowed range 1-24 hours).\n\nSambee issues short-lived API tokens (up to 60 minutes) while the browser session remains valid. With a refresh token, Sambee can renew through the IdP until the authentication-age limit. Without one, Sambee can issue another API token from the browser cookie only until the fixed session limit. Reducing that limit shortens existing no-refresh sessions; increasing it does not extend them. When the applicable deadline arrives, Sambee starts a new top-level IdP authorization, which might reuse the IdP's existing SSO session.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n- **Session renewal** reports whether this particular test returned a refresh token. A test without one can still succeed; users will need to sign in again after the configured no-refresh session limit.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n"}, "page_contents": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- Scopes:\n   - `openid`: required\n   - `profile`: often necessary for the provider to return `preferred_username`, which Sambee requires\n   - `email`: optional\n   - `groups`: required when using group admission or group-based role mappings\n   - `offline_access`: may be required for refresh tokens, depending on the provider\n- Authorization code grant\n- Refresh token grant: optional\n\n#### Token Lifetimes\n\nConfigure token lifetimes:\n\n- Refresh token, if the provider issues one:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n#### Refresh Tokens\n\nHaving the provider issue refresh tokens is recommended as that enables background session renewal without user interaction.\n\nProviders that don't issue refresh tokens can still be used with Sambee. They must return an ID token with a valid `auth_time` claim when Sambee requests `max_age`.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid` and every scope required for the configured claims, such as `profile` and `email`. Add `groups` for group admission or group-based role mappings. Add `offline_access` only if supported and needed for provider refresh tokens. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control the maximum age of a verified IdP sign-in. The default is 30 days.\n\nSet **Session limit without refresh token (hours)** separately for sign-ins that return no refresh token (default 8 hours; allowed range 1-24 hours).\n\nSambee issues short-lived API tokens (up to 60 minutes) while the browser session remains valid. With a refresh token, Sambee can renew through the IdP until the authentication-age limit. Without one, Sambee can issue another API token from the browser cookie only until the fixed session limit. Reducing that limit shortens existing no-refresh sessions; increasing it does not extend them. When the applicable deadline arrives, Sambee starts a new top-level IdP authorization, which might reuse the IdP's existing SSO session.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n- **Session renewal** reports whether this particular test returned a refresh token. A test without one can still succeed; users will need to sign in again after the configured no-refresh session limit.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/openid-connect-authentication-operations", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "openid-connect-authentication-operations", "title": "Openid Connect Authentication Operations", "path": "admin-guide/authentication/openid-connect-authentication-operations", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 25, "diff_removed": 4}}, "content_versions": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nWhen a provider returns a refresh token, Sambee stores it encrypted on the server. If the provider returns none, Sambee stores no provider token. In both cases, the browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing provider tokens to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background while the session remains valid. A session with a refresh token is limited by the configured interactive sign-in interval (default 30 days from the verified IdP authentication). A session without a refresh token has a fixed limit of 8 hours from the callback by default, configurable from 1 to 24 hours. Neither local activity nor API-token renewal extends that deadline; the earlier applicable deadline always wins. Reducing the no-refresh limit permanently shortens existing sessions, including pending sign-ins.\n\nA new top-level authorization is required when the applicable deadline ends, the identity provider rejects or revokes a refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. The IdP might use its SSO cookie to return quickly, but this is not guaranteed. Sambee returns the user to the same safe route after sign-in. Registered text and Markdown drafts are snapshotted before an authentication redirect when storage is available; other unsaved work might be interrupted. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for limitations and recovery behavior.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Local Username Matching And Upgrade Conflicts\n\nLocal-password sign-in matches usernames without regard to capitalization, using Unicode case folding and ignoring leading and trailing whitespace. Stored spelling is preserved. Passwords remain case-sensitive. New accounts and renamed accounts can't introduce case-insensitive duplicates, including accounts created through OIDC.\n\nUpgrades complete automatically even if existing accounts have conflicting names, such as `UserA` and `usera`. Accounts, passwords, roles, ownership, and identity links are preserved. Each conflicting account continues to accept only its exact stored username spelling; other capitalizations are rejected without choosing an account by its password. Disabled, expired, and passwordless accounts also count toward a conflict.\n\n**Settings** \u003e **Administration** \u003e **Users** lists conflicts in a warning, regardless of directory filters or pagination. Resolve a conflict by renaming an account through its normal editor, or deleting an account that's no longer needed. Deleting an account remains subject to the normal deletion consequences and administrator safeguards. Unchanged usernames and case-only renames remain available while resolving existing conflicts. Once only one account has a comparison key, case-insensitive password sign-in applies automatically, without restarting or rerunning a migration.\n\nOIDC identity matching and automatic linking still require the exact username spelling. A case-only match doesn't automatically link an identity or create another account; resolve that collision through the existing identity-mapping controls.\n\n## Require A Local Password Change\n\nWhen creating a local user or resetting an existing local password, enable **Require change on next password sign-in** to require a new password before the user can continue. The user directory shows **Pwd change req'd** while this requirement is pending.\n\nAfter signing in with the temporary or existing local password, the user must enter that password, choose a different password, and confirm it. They can sign out instead, but can't browse files, use administration settings, or issue companion credentials until the change succeeds. Successful changes invalidate existing Sambee tokens and require another sign-in.\n\nThe requirement applies only to local-password sessions. A linked user can still sign in through OIDC; that doesn't clear the local-password requirement or change the identity provider's password. Passwordless OIDC accounts have no local password to reset. In **OIDC only** mode, local password changes are unavailable.\n\nExisting password-change flags are enforced after upgrading. They aren't cleared automatically. If a user can't complete the change, an administrator can set another local password through User Management. Switch the requirement off during that reset only when the replacement password is intended to be permanent. Authentication-disabled mode doesn't enforce the change workflow.\n\n## Audit Events\n\nOIDC configuration, identity events, and successful local password changes and resets are stored in the Sambee database. They do not contain passwords, raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\nAll capitalization and Unicode case-folding variants of a username share the same username-based password limit, including legacy conflicting accounts.\n"}, "page_contents": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nWhen a provider returns a refresh token, Sambee stores it encrypted on the server. If the provider returns none, Sambee stores no provider token. In both cases, the browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing provider tokens to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background while the session remains valid. A session with a refresh token is limited by the configured interactive sign-in interval (default 30 days from the verified IdP authentication). A session without a refresh token has a fixed limit of 8 hours from the callback by default, configurable from 1 to 24 hours. Neither local activity nor API-token renewal extends that deadline; the earlier applicable deadline always wins. Reducing the no-refresh limit permanently shortens existing sessions, including pending sign-ins.\n\nA new top-level authorization is required when the applicable deadline ends, the identity provider rejects or revokes a refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. The IdP might use its SSO cookie to return quickly, but this is not guaranteed. Sambee returns the user to the same safe route after sign-in. Registered text and Markdown drafts are snapshotted before an authentication redirect when storage is available; other unsaved work might be interrupted. See [Recover Unsaved In-Browser Edits](../../../user-guide/view-and-edit-files/recover-unsaved-edits/) for limitations and recovery behavior.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/account-and-preferences/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Local Username Matching And Upgrade Conflicts\n\nLocal-password sign-in matches usernames without regard to capitalization, using Unicode case folding and ignoring leading and trailing whitespace. Stored spelling is preserved. Passwords remain case-sensitive. New accounts and renamed accounts can't introduce case-insensitive duplicates, including accounts created through OIDC.\n\nUpgrades complete automatically even if existing accounts have conflicting names, such as `UserA` and `usera`. Accounts, passwords, roles, ownership, and identity links are preserved. Each conflicting account continues to accept only its exact stored username spelling; other capitalizations are rejected without choosing an account by its password. Disabled, expired, and passwordless accounts also count toward a conflict.\n\n**Settings** \u003e **Administration** \u003e **Users** lists conflicts in a warning, regardless of directory filters or pagination. Resolve a conflict by renaming an account through its normal editor, or deleting an account that's no longer needed. Deleting an account remains subject to the normal deletion consequences and administrator safeguards. Unchanged usernames and case-only renames remain available while resolving existing conflicts. Once only one account has a comparison key, case-insensitive password sign-in applies automatically, without restarting or rerunning a migration.\n\nOIDC identity matching and automatic linking still require the exact username spelling. A case-only match doesn't automatically link an identity or create another account; resolve that collision through the existing identity-mapping controls.\n\n## Require A Local Password Change\n\nWhen creating a local user or resetting an existing local password, enable **Require change on next password sign-in** to require a new password before the user can continue. The user directory shows **Pwd change req'd** while this requirement is pending.\n\nAfter signing in with the temporary or existing local password, the user must enter that password, choose a different password, and confirm it. They can sign out instead, but can't browse files, use administration settings, or issue companion credentials until the change succeeds. Successful changes invalidate existing Sambee tokens and require another sign-in.\n\nThe requirement applies only to local-password sessions. A linked user can still sign in through OIDC; that doesn't clear the local-password requirement or change the identity provider's password. Passwordless OIDC accounts have no local password to reset. In **OIDC only** mode, local password changes are unavailable.\n\nExisting password-change flags are enforced after upgrading. They aren't cleared automatically. If a user can't complete the change, an administrator can set another local password through User Management. Switch the requirement off during that reset only when the replacement password is intended to be permanent. Authentication-disabled mode doesn't enforce the change workflow.\n\n## Audit Events\n\nOIDC configuration, identity events, and successful local password changes and resets are stored in the Sambee database. They do not contain passwords, raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\nAll capitalization and Unicode case-folding variants of a username share the same username-based password limit, including legacy conflicting accounts.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:developer-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "developer-guide", "title": "Developer Guide", "path": "developer-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Developer Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "0.8": "+++\ntitle = \"Developer Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "0.9": "+++\ntitle = \"Developer Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "1.0": "+++\ntitle = \"Developer Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "2.0": "+++\ntitle = \"Developer Guide\"\n+++\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/project-orientation", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "project-orientation", "title": "Project Orientation", "path": "developer-guide/project-orientation", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "0.8": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "0.9": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "1.0": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "2.0": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/project-orientation/what-sambee-consists-of", "parent_id": "section:developer-guide/project-orientation", "depth": 2, "kind": "page", "label": "what-sambee-consists-of", "title": "What Sambee Consists Of", "path": "developer-guide/project-orientation/what-sambee-consists-of", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.8": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.9": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "1.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "2.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n"}, "page_contents": {"0.7": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.8": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.9": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "1.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "2.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/project-orientation/repository-tour", "parent_id": "section:developer-guide/project-orientation", "depth": 2, "kind": "page", "label": "repository-tour", "title": "Repository Tour", "path": "developer-guide/project-orientation/repository-tour", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.8": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.9": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "1.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "2.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.8": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.9": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "1.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "2.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/local-development-workflow", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "local-development-workflow", "title": "Local Development Workflow", "path": "developer-guide/local-development-workflow", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "0.8": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "0.9": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "1.0": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "2.0": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/local-development-workflow/set-up-the-development-environment", "parent_id": "section:developer-guide/local-development-workflow", "depth": 2, "kind": "page", "label": "set-up-the-development-environment", "title": "Set Up The Development Environment", "path": "developer-guide/local-development-workflow/set-up-the-development-environment", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 7, "diff_removed": 0}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 13, "diff_removed": 2}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "0.8": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).", "0.9": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "1.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "2.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "0.8": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).", "0.9": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "1.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "2.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/local-development-workflow/common-task-commands", "parent_id": "section:developer-guide/local-development-workflow", "depth": 2, "kind": "page", "label": "common-task-commands", "title": "Common Task Commands", "path": "developer-guide/local-development-workflow/common-task-commands", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 16, "diff_removed": 0}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.8": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.9": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "1.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "2.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.8": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.9": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "1.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "2.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/backend-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "backend-architecture", "title": "Backend Architecture", "path": "developer-guide/backend-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "0.8": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "0.9": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "1.0": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "2.0": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/backend-overview", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "backend-overview", "title": "Backend Overview", "path": "developer-guide/backend-architecture/backend-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.8": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.9": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "1.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "2.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.8": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.9": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "1.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "2.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/request-flow-and-service-boundaries", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "request-flow-and-service-boundaries", "title": "Request Flow And Service Boundaries", "path": "developer-guide/backend-architecture/request-flow-and-service-boundaries", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.8": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.9": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "1.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "2.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.8": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.9": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "1.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "2.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/image-preprocessing-and-conversion-pipeline", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "image-preprocessing-and-conversion-pipeline", "title": "Image Preprocessing And Conversion Pipeline", "path": "developer-guide/backend-architecture/image-preprocessing-and-conversion-pipeline", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/smb-change-notification-and-directory-freshness", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "smb-change-notification-and-directory-freshness", "title": "Smb Change Notification And Directory Freshness", "path": "developer-guide/backend-architecture/smb-change-notification-and-directory-freshness", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 240, "diff_removed": 199}}, "content_versions": {"0.7": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses two separate SMB2/SMB3 `CHANGE_NOTIFY` paths: one tells an open browser to refresh its directory listing; the other maintains the directory-search index. They have different subscription, event, and consistency rules.\n\n## Components\n\n| Component | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | Browser subscriptions, access checks, path-prefix mapping, and `directory_changed` delivery |\n| `backend/app/services/directory_monitor.py` | Shared per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | Per-connection index lifecycle, recursive directory-name notifications, and background verification |\n| `backend/app/services/directory_index.py` | SQLite storage, generations, search, and maintenance |\n| `backend/app/services/directory_traversal.py` | Handle-bound SMB enumeration, identity validation, and exact missing-child checks |\n| `companion/src-tauri/src/server/directory_manager.rs` | Local-drive index lifecycle, native observations, and background workers |\n| `backend/app/main.py` | Backend monitor and cache shutdown |\n\n## Browser Notifications\n\n### Subscriptions and Paths\n\n`DirectoryMonitor` shares one `MonitoredDirectory` per `connection_id:path`. The first subscriber starts it; the last unsubscribe stops it. A WebSocket disconnect must release that client's subscriptions.\n\nThe WebSocket layer uses user-facing paths. `ConnectionManager` applies the connection's `path_prefix` to obtain the native SMB path. Notification callbacks map that path back to the user-facing path before delivery. Subscription keys and native watch paths must not be used interchangeably.\n\n| Message | Example |\n|---|---|\n| Subscribe | `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n| Unsubscribe | `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n| Change notification | `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n\n### Events and Refreshes\n\nBrowser watchers observe file names, directory names, sizes, and last-write changes in the subscribed directory's immediate children. They do not watch the whole subtree. A deep write does not invalidate every ancestor listing, although metadata changes reported for an immediate child directory can trigger a refresh.\n\nThe browser retains loaded rows during automatic refresh, including an empty listing. It waits for an active listing request, combines notifications into one pending refresh, and starts at most one automatic refresh per second. Navigation and pane disposal cancel queued refreshes.\n\n`directory_changed` requests a new listing; it is not a file-difference protocol. See [File Browser and Navigation Model](../../frontend-architecture/file-browser-and-navigation-model/) for browser state and request handling.\n\n### Resource Ownership\n\nA monitor acquires its connection, session, tree, directory handle, and `FileSystemWatcher` in that order. Cleanup runs in reverse order, including after partial initialization.\n\nCancellation during startup retains the pending worker. When startup finishes, cleanup releases only the subscription acquired by that worker, not a replacement subscription. Shutdown rejects new monitor startup.\n\nTransient failures use capped exponential reconnect backoff with jitter. Recovery continues after fast retries are exhausted, while the subscription remains active. Deletion of the watched directory stops its monitor. A stopped monitor is not reused for new subscribers. Shutdown calls `shutdown_monitor()`; a worker that is still running retains its handles until it exits.\n\n## Directory-Index Consistency\n\nThe backend and companion maintain SQLite directory indexes through shared background managers, not per-request tree walks. Cold queries return status while initialization proceeds. Committed initial batches are searchable with partial coverage; result limits do not limit indexed coverage or exact match counts.\n\nThe index watcher observes directory-name changes recursively from the share root or configured prefix. Events drive parent reconciliation. Periodic full verification covers missed notifications; it must not become a full rescan on every navigation or query.\n\n### Generations and Observation Order\n\nFull verification updates the selected generation in place while retained data remains searchable. Interrupted first builds and active verification passes keep their rows, pass identity, and queued parents, including item issues and storage reopens. A completed full pass advances `last_verified_at_ms` even with item issues; incremental changes and queries do not. Each index retains one generation, with `building` for an initial build and `accepted` after completion.\n\nNon-root access failures, unsafe traversal, invalid names, and other item read errors do not stop a pass. The scanner skips an invalid name or completes a failed parent, then continues with readable siblings. A failed parent retains stored descendants, including batches already published during the current read. Acceptance retains the issue count and sets partial coverage. It clears the verification request and uses the regular verification interval, not a special item retry. Event loss still blocks acceptance and keeps coverage uncertain. Root, transport, authentication, resource-limit, and storage failures retain their retry and recovery rules.\n\nRead tokens and observation barriers reject stale results. Observed directory changes update the index and request verification, but they do not change coverage. Lost events or pending-observation queue overflow mark coverage uncertain and request verification without deleting retained data. Pass acceptance requires a valid root and no outstanding observations or reads that could invalidate the pass.\n\nDirectory rows, FTS entries, counts, issues, queued subtree work, and revision updates must remain transactionally consistent. Queries read results and metadata from one selected-generation transaction.\n\n### SMB Watcher Startup\n\nBackend initialization waits up to 10 seconds for the first watcher attempt before it probes the source root or scans directories. Success means that the first `CHANGE_NOTIFY` request has been sent and startup invalidation has completed, not just that the thread or connection has started. The wait is asynchronous and holds no scan slot, worker, coordinator lock, or generation lock.\n\nA connection failure, notification-start failure, or timeout permits fallback verification. Watcher retries continue in the background. A failed first attempt reports unavailable monitoring, not lost observations before monitoring started. The first-attempt result is separate from current monitoring readiness. Cancellation and shutdown remove the waiter and prevent a later scan from starting.\n\nIf the watcher first becomes ready during fallback verification, it changes the epoch. Pre-monitoring reads cannot commit. Verification resumes after the bounded observation retry; a valid root probe keeps retained results searchable. Normal successful startup captures its scan epoch after watcher setup and needs no startup retry.\n\n### SMB Barriers and Local Retries\n\nThe backend captures an epoch for each full pass without registering a pass-wide reader. A directory read depends on that directory, its direct children, and its ancestors. A barrier on a deeper descendant does not reject the ancestor listing. A root barrier rejects all content reads. Source-root availability probes check epoch and reader ownership, not directory-content barriers.\n\nObservations update the selected generation before their barriers retire. Barriers remain only while pending observations or older live parent reads need them. When retained barriers exceed their count or byte bound, they collapse to one current root barrier. Live content reads become stale, but the epoch does not change and pending hints remain available.\n\nA stale parent stays pending and moves to the queue tail in one transaction. Published child batches remain; deferral clears their staged snapshot names. The next read re-enumerates the parent and starts a fresh snapshot. Local stale reads, final-capture refusals, and transient parent errors do not invalidate unrelated completed work. Observation loss and exhausted read capacity cause bounded revalidation of retained completed parents. Other epoch changes do not restart completed parents.\n\nThe periodic loop checks due verification before incremental reconciliation. A full pass owns the selected generation's scan queue; separate reconciliation does not run during that pass. Completed buffered ancestors commit before descendants are selected, so deleted rows and refreshed FileIds take effect first. Stale reads use the one-second observation retry; source-wide failures keep the failure backoff. Quiet branches can progress, but a full pass cannot be guaranteed to finish while relevant directories keep changing.\n\nLarge reads store early snapshot names in `scan_snapshot_children`, owned by the pending parent queue row. This keeps memory bounded without separate per-child absence requests. The final diff considers both staged names and the final child batch. Direct-child changes still reject the read before parent completion. Failed parent reads preserve stored children instead of applying an incomplete deletion diff.\n\n### Parent Reconciliation\n\nBackground workers reconcile affected parents between full passes. Renames check both parents, and new directories trigger descendant reads. A completed listing under a held, validated parent drives the atomic child diff; an incomplete listing or access error cannot delete missing children. Streamed reads use the same disk-backed snapshot names as full passes. An item error records partial coverage, completes the parent, and retains its stored subtree. Source-wide failures and stale observations leave work pending. Reconciliation does not establish full verification or clear uncertain coverage.\n\nFile operations queue parent hints before dispatch and after actual worker completion, including failure. New mutation paths must preserve this rule. Cancellation must not release worker ownership early or change the original operation result when hint delivery fails.\n\n### Source Identity and Traversal\n\nCatalogue names are SHA-256 hashes of source boundary settings. SMB uses the connection ID, host, port, share, configured folder, and username. Passwords, display names, connection edit times, and runtime session IDs do not change the file name. Local sources use the configured root path and, for fixed, removable, and unknown drives, available volume serial or file-system UUID evidence. Network and virtual drives use the root path alone. Runtime session IDs remain diagnostic values.\n\nReused rows are unverified until a verification pass completes. An SMB reconnect binds new handles and invalidates unfinished reads. Queued child FileIds are expected read identities, not proof of storage continuity. SMB server GUIDs and volume metadata are diagnostic values. File IDs of zero or all ones are unavailable and are not queued as expected identities. Session and tree IDs are compared only within one connection.\n\n| Source | Traversal rules |\n|---|---|\n| SMB | No automatic DFS or symlink retries on compound reads; no-delete root handles; observed direct-parent reads only with healthy monitoring and a queued FileId; retained ancestors for safe fallback; connection-scoped session, tree, file-ID, and bound native-path checks |\n| Linux local drive | Retained directory descriptors, `openat2` with no-link, no-mount, and beneath-root resolution; component-by-component fallback when the syscall is unavailable; exact names and mount checks; kernel pseudo-filesystems and device-tree aliases excluded |\n| Windows local drive | No-delete bound-root handles, delete-sharing full-pass parent handles, 128-bit file IDs, volume and native-device paths; bounded enumeration and strict UTF-16 decoding |\n\nThe SMB boundary is logical: the configured share and folder. A configured subfolder is not an access-control boundary; the connection credentials can access the share. Storage mounted inside a share can be indexed; SMB does not promise physical-volume containment. DFS shares and reported reparse descendants remain excluded. Local traversal does not cross mounts. Windows junctions, name-surrogate redirections, cloud placeholders, and unknown reparse tags are excluded rather than followed. Missing optional volume metadata does not weaken these traversal checks.\n\nSMB full passes check the bound root at the start and end. Between these checks, a known parent can use a direct no-follow open without an ancestor chain only while the recursive folder-change watcher is ready and the epoch has no observation-loss or read-capacity invalidation. The opened FileId must match the queue, the handle must not report a reparse point, and the requested native path, session, and tree must match the binding. Root and reconciliation reads, missing-parent recovery, and exact child checks retain the safe ancestor chain. Parents without a queued FileId also use the safe path.\n\nObservation protects index correctness on the direct path. An ancestor event rejects affected reads before publication. Tokens remain live until grouped commits and check watcher readiness again at commit. A late event corrects already committed rows through the normal mutation path; the index is eventually consistent with the watcher delay. If monitoring is lost during a pass, active observed reads are deferred and the pass continues with safe reads. Observation loss requeues completed parents for revalidation, while coverage can remain uncertain. Root and non-compound scan handles retain no-delete sharing.\n\nDuring a full pass, safe reads reuse the pinned share and configured-root handles. Between full probes, local checks require connected handles, a non-DFS tree, the same connection object and server GUID, and unchanged session and tree IDs. Descendant ancestor chains and target FileAll identity checks remain. Closing a parent read does not close the root handles. A source-read failure requests a full root probe before a later read; versioned requests preserve failures that occur during a probe. Standalone reconciliation retains full root checks rather than relying on full-pass boundaries.\n\nSafe reads reuse cached `FsVolume` metadata across handles on the same live tree. The cache matches the tree and connection objects plus the session and tree IDs. A changed binding requires a new volume query. Unsupported optional volume information is cached for that binding; permission and transport failures are not cached. This cache does not replace root or parent verification.\n\n### SMB Compound Reads\n\nThe observed reader sends one related compound: `CREATE`, `QUERY_INFO(FileInternalInformation)`, two `QUERY_DIRECTORY` requests, and `CLOSE`. The first directory query restarts enumeration; the second continues it. End-of-directory responses complete a small or empty directory in one round trip. If both queries return data, the reader discards those partial results and opens the parent again through the existing enumeration loop.\n\nEach query buffer is bounded by the negotiated transaction size, the shared 1 MiB maximum, and available credits. A connection without multi-credit support uses at most 64 KiB. Full scans send up to `scan_pipeline_depth` compounds before receiving the oldest result. The shared default is eight parents. All reads use one worker and the root's retained connection; reused session and tree IDs cannot admit a replacement transport.\n\nBefore each pipeline send, the reader checks the credit window under the connection lock and leaves `scan_credit_reserve` credits, with a shared default of 16. Scan requests ask for credit growth until the window can support the configured depth. If a compound cannot fit, the worker receives the oldest outstanding parent first. With no outstanding reads, it can send one bounded credit-growth echo per queue page, including when the window starts at one credit. If the server does not grant enough credits, the reader uses the existing loop instead.\n\nThe pool creates a `ScanCreditConnection` before transport setup and lets `smbclient` register its session with the configured authentication and encryption policy. Its reentrant sequence lock covers the full scan credit check and compound send. Ordinary browse sends use the same lock, so they cannot consume credits between the scan check and the library's per-message allocations. The check uses the library's negotiated credit charges, with a minimum of one credit per message. If the full compound and reserve do not fit, admission changes no sequence numbers or outstanding requests. The lock is released before receiving responses.\n\nConnections without this atomic-admission method use the existing loop instead of an unprotected pipeline send. A failed compound send still retires and aborts that connection generation rather than reusing uncertain request state.\n\nThe loop also adapts its query buffer before each request. It uses the negotiated transaction size and the shared 1 MiB maximum, then limits the size to the current credit budget. It leaves the browse reserve where possible, but retains a one-credit query when the window is small. Connections without multi-credit support use at most 64 KiB. These size estimates do not add atomic admission to loop reads; the whole-compound lock applies to pipeline sends.\n\nCompound handles allow read, write, and delete sharing because they open and close within the same request group. The reader disables client-side symlink retries and drains responses after a parent error. Each in-flight read has a deadline measured from submission. A timeout, including during cleanup after watcher loss, defers unfinished parents and retires the connection generation through the pool's abort path. A mutation barrier on one parent defers only that parent; unrelated valid results remain eligible for grouped commit in queue order. Watcher loss defers all outstanding observed reads before the pass continues with safe traversal.\n\nFileId mismatches, reparse attributes, malformed responses, and listings that make no progress cannot publish children. Missing-path and access-denied responses retain their existing cache error handling. Buffered results still check observation and local root binding during enumeration and before commit. Exact child checks reopen the safe retained-ancestor reader.\n\nThe drive browser and local index share one classifier. USB, SD, MMC, and hot-plug disks are removable even when Windows reports a fixed drive. Failed classification uses the unknown class. Fixed drives select another index only when available volume serial or UUID evidence changes. Removable and unknown drives also replace the current generation when available label, file-system type, or total-capacity evidence changes. Generation replacement selects the new generation and deletes the old one in one transaction. Unchanged volume evidence does not rewrite source metadata. Missing evidence and drive-class changes alone do not replace data. Windows uses the 64-bit serial from `FILE_ID_INFO`, including zero. Local file IDs are session-scoped checks, not replacement signals.\n\nVolume evidence is checked again when the root binds. An unmounted Linux source stays unavailable instead of indexing its mount-point folder. Linux mount checks use descriptor-bound `statx` mount IDs with `/proc/self/fdinfo` as a fallback. A missing mount-boundary capability stops that source until Companion restarts. Idle removable sources without active work or a watcher release their root handles. Windows removal notifications pause source work and release handles before removal is allowed.\n\nDepth and path-length bounds are defined in `shared/directory-index/contract.json`. Excluded descendants produce partial coverage while readable branches continue.\n\nLinux enumeration uses `d_type` to skip regular files without a metadata call. Unknown entry types use a no-follow metadata check. A no-follow `statx` checks each directory child's inode and mount without opening the child. Missing statx fields use the descriptor fallback. Windows enumeration uses a 1 MiB buffer and validates names, attributes, reparse tags, and full 128-bit FileIds from directory records without opening each child.\n\nA native scan uses one `NativeParent` read through enumeration, batch validation, issue handling, and parent completion. It checks the queued identity before processing children and keeps the observation token checks before writes. Linux retains the parent descriptor and gives `fdopendir` a duplicate, so enumeration cannot close the original. Descriptor checks reject a deleted parent without reopening its path. If the watcher is missing, failed, or not yet ready, Linux also checks the root-relative parent identity before each child batch and final parent completion, including parallel full-pass and reconciliation reads. A healthy watcher adds no parent opens at these boundaries. Windows full-pass reads use FileId opens, relative no-reparse opens, or the checked ancestor fallback. Non-root scan handles permit read, write, and delete sharing. The bound root and strict standalone reads keep no-delete sharing. Identity and native-path checks reject a moved parent before publication. Missing-parent recovery uses exact child lookups under the retained parent.\n\nFull passes read independent parents with at most four native worker threads, defined by `scan_read_parallelism`. A bounded channel sends child batches, issues, and completion to the scan thread; workers never write the index. Each read retains its handle and observation token until publication or discard. Queued ancestors finish and commit before their descendants start, so changed FileIds reach later reads. Cancellation and storage failure stop new jobs, drain ownership, and join all workers.\n\nBackend initialization withholds rows until a handle-bound root probe succeeds. Root failure returns HTTP 503 without deleting accepted data. Descendant access denial produces partial coverage instead. Late results cannot restore an invalidated source.\n\n### SQLite Storage\n\n| Runtime | Location and driver |\n|---|---|\n| Backend | `data/directory_cache/sqlite/`, or `sqlite/` below `directory_cache_location`; standard Python `sqlite3` with Debian system SQLite |\n| Companion | `directory-index/sqlite/` in the OS-user cache directory; bundled Rust SQLite binding |\n\nIndexes are disposable directory data, separate from recent history. Stored source metadata excludes passwords. `shared/directory-index/` owns the schema, search normalization, validation rules, and contract fixtures.\n\nSchema version 5 retains nullable FileIds in `scan_queue`: eight bytes for SMB and Linux, and 16 bytes for Windows. Root and observed-parent entries can omit an identity. Child identities commit with directory rows and survive a deferred read or reopen. Full passes and reconciliation refresh existing queue rows when a parent listing supplies a different non-null identity. Reconciliation does not insert a job for an existing child that has no queue row. A change from a known identity requeues completed child work; a change from an unknown identity keeps its processed state. Unchanged identities cause no queue writes. Readers compare a queued identity before publishing children. Companion can first commit a fresh buffered parent listing to update that identity. A confirmed mismatch is an unsafe item issue.\n\nDirectory rows have a nullable `parent_id` and the `directories_parent(generation_id, parent_id)` index. Stored links must identify an immediate parent in the same generation. Deletes cascade to linked descendants, their FTS entries, and their queue rows. Adds and moves maintain parent links. Both scanners diff complete and streamed parent snapshots and finish their queue rows in one transaction without rewriting unchanged directory or FTS rows. Early batches store their names in `scan_snapshot_children`. Final completion removes absent linked subtrees, clears staged names, and completes the parent atomically. Failed parents suppress deletions. Old-schema indexes rebuild through disposable-cache recovery; recent history is not changed.\n\nItem issue counts belong to the producer's observation token. Full passes buffer these counts until the completed parent snapshot commits; reconciliation commits them with the final parent snapshot. Early incomplete child batches retain the pending counts. A stale token discards them and leaves its parent pending. Counts aggregate by issue code in the parent transaction, so coverage, revision, directory changes, and parent completion roll back together if a write fails. Buffered issue payloads count toward the group byte bound.\n\nBoth source managers retain a process-local sample of affected parent paths and issue codes after successful parent commits. The sample uses the shared `max_logged_scan_issues_per_pass` bound, removes resolved parent entries after clean reads, and resets for a new full pass. Successful delete observations and parent snapshots also remove samples for deleted subtrees; failed database writes retain the samples. It is not persisted or added to the index schema. Ordinary search responses expose `issue_details_available`; `include_issue_details=true` additionally returns `issue_details` and `issue_details_incomplete`. These details use the same source authorization as directory search. A listed parent can identify a location containing an unreadable child name rather than an unreadable parent itself.\n\nThe selected generation records `scan_pass_id` and `scan_active`. A fresh verification resets its queue completion flags and starts a new pass; an interrupted active pass resumes without that reset. A completed pass keeps the selected generation ID. The clean-shutdown marker is cleared on open and set only after a clean, transaction-free close with ready search tokens. A clean reopen skips SQLite `quick_check` and the FTS integrity command when the FTS schema is intact. An unclean reopen runs both checks. Schema, foreign-key, generation, and storage-binding validation still run on every open. Reopen retains valid streamed snapshot names; the first restarted batch replaces them. Invalid names or snapshots owned by completed parents trigger disposable-cache recovery.\n\nBoth stores use WAL and `synchronous=NORMAL`. The index is a verified cache, not the source of directory data. A power failure can lose recent cache commits; interrupted or uncommitted work remains pending for verification. Writes, checkpoints, maintenance, and close are serialized through the writer. Queries use read-only connections and explicit transactions. Both runtimes reuse isolated read connections and check their storage binding before each query. Query cancellation handlers are cleared before reuse. Storage leases remain held until admitted readers and workers finish; active database families cannot be evicted.\n\nScan writes use bounded parent groups. Content-changing groups have a 250 ms maximum wait and a 1,000-parent cap. Bookkeeping-only groups have a 1 s maximum wait and a 20,000-parent cap. Each interval starts with the first parent, not the previous commit. Both groups commit early at the parent cap or the shared byte bound; parent names count toward that bound. Independent work pages do not force a commit. Ancestor dependencies, error transitions, and pass completion can require an earlier commit. Each completed parent keeps its observation token and barriers until commit, but no longer uses active-reader capacity. The next page excludes completed buffered parents. A stale parent remains pending; valid parents in the group can commit. Large parent reads can publish child batches before the parent is complete.\n\nReconciliation uses the same adaptive groups as full passes without advancing the full-verification clock. Queue paths and FileIds are read in pages, and buffered completed parents are excluded from later pages. Ancestors commit before queued descendants start. Backend reconciliation uses the page's FileIds and keeps its per-parent worker deadline. Native reconciliation uses the bounded worker scheduler but retains strict root and parent opens, rather than full-pass fast opens. Early snapshots, issue counts, stale deferral, and ownership cleanup use the reconciliation generation checks. Status snapshots refresh after group commits.\n\nEmpty-query status uses committed metadata snapshots in memory. It does not open SQLite connections or run a directory query. The optional `scan_progress` response contains the phase, completed and queued parent counts, directory count, and start timestamp. Each group commit refreshes progress. The frontend shows active build or update progress before uncertain coverage.\n\nThe `cache_state` value `opening` identifies index initialization before scanning. The quick bar hides this status but continues polling. Errors and recovery messages remain visible. Once scanning starts, build or update progress replaces the opening state. A build shows `Indexing...` until its directory count is positive; zero is not shown as a directory result.\n\nStorage must be private and local. Opens and cleanup validate directory ownership, file identity, and aliases. Do not write to managed databases externally or weaken these checks to permit a path-only fallback.\n\n### Resource Controls\n\nWorker counts, batches, and observation queues are bounded by the shared contract. Disk growth requires headroom and free-space admission. Native full-pass and reconciliation groups share one disk reservation for their writes. Ordinary admission reuses its free-space sample for the final reservation check while holding the accounting lock. If cleanup runs, admission takes a fresh sample before it reserves space. Outstanding reservations remain part of both budget and physical-space checks. Maintenance yields to active work.\n\nAutomatic full passes have a minimum spacing of 30 seconds, defined in the shared contract. Requests cannot bypass this limit or failure backoff. Interrupted passes retain completed directory work and item issues. After an observation gap, retained directory reads are revalidated in bounded batches before pass acceptance. Parent reconciliation does not start a new full pass or advance the full-verification clock.\n\nPolicy defaults and ranges belong to `shared/directory-index/contract.json`. A lower budget may pause growth but must not trim active data. Eviction applies only to inactive, unowned indexes. Disk and cache settings are not hard filesystem or process-memory ceilings.\n\nSee [Directory-Index Policy Delivery](../../companion-architecture/local-drive-and-save-back-pipeline/#directory-index-policy-delivery) for Companion ownership and [Manage Directory Search](../../../admin-guide/operations-and-maintenance/manage-directory-search/) for administration.\n\n### Recovery and Shutdown\n\nStartup validates source identity and application consistency before exposing rows. Damaged search tokens rebuild from validated directory rows. Replacement is restricted to recognized invalid index data; permission, capacity, busy-storage, and general I/O failures must not trigger discard.\n\nFailures use bounded retries. Requests must not bypass retry deadlines. Access updates only the last-access time; an idle gap does not invalidate observations or make a running source unavailable. Idle sources release resources only when no worker, reader, or queued scan work remains. Released sources revalidate the root on reuse. Shutdown waits for admitted work before closing storage and root ownership, even when a request has been cancelled.\n\nFor the backend, scan work waits for both the resource-failure and observation-retry gates. The scan delay is therefore the later active deadline. `retry_after_ms` reports the earlier of that scan deadline and the next watcher retry. Status requests and searches do not move these deadlines. A local stale read uses the one-second observation retry, not a new failure backoff or a new full-pass interval.\n\nBackend and Companion epoch invalidations record a diagnostic reason: `watcher_start`, `observation_loss`, `source_rebind`, `read_capacity`, `stalled_read`, or `lifecycle`. These cover first notification setup, lost observations, source rebinding, exhausted read admission, stalled workers, and lifecycle changes. All reasons request verification. All reasons except `stalled_read` also mark coverage uncertain, because they can lose source events. A stalled read loses no events, so the next accepted pass can verify the index. Epoch and ownership checks reject stale work. The SMB observed path also stays disabled in an epoch with observation loss or exhausted read capacity, even after the queue-revalidation flag is consumed. Each invalidation logs its reason and a counter at INFO, including repeated reasons. Pass start and finish events also use INFO. Finish events include parent and directory counts, group commits, duration, and an abort reason when the pass fails.\n\nIndex recovery does not reset a shared SMB connection or remove recent-directory history. A source binding mismatch pauses publication, re-binds source handles, and schedules verification. Source and storage failures are not evidence that a directory was deleted.\n\nSMB setup runs outside the shared pool lock. Concurrent requests share setup for the same private cache. The pool bounds admitted work, setup tasks, and retained connection generations, both per source and across the process. A retired generation keeps its own cache until its workers and cleanup finish; replacement requests use a separate cache. Capacity failures return retry information rather than enter an unbounded queue. Shutdown stops new admission. Writes are not replayed automatically.\n\nA caller timeout or cancellation does not itself stop a blocking SMB operation. Reader handles, connection leases, and worker permits remain owned until actual completion. Late successful opens are closed before their leases are released.\n\nAn operation deadline retires its connection generation and requests one pool-owned transport abort through public `Connection.disconnect(close=False)`. The abort runs outside the event loop and pool lock, uses a snapshot of that generation's connections, and does not send session logoff requests or touch replacement connections. Ordinary caller cancellation retains work without aborting unrelated operations on the shared generation. Long-lived watcher subscriptions use their own lifecycle, not ordinary operation deadlines.\n\nPublic abort wakes blocked receive requests in the installed client. It cannot provide a universal operation deadline: disconnect shares a lock with socket send and can remain blocked behind a send. Abort work retains capacity until it exits. If workers cannot finish, admission remains bounded and requests return capacity errors. Wait before retrying; restart the backend service if retained work continues to occupy capacity.\n\nA mutation interrupted by abort, or whose caller deadline expires after dispatch, has uncertain completion. The API reports `smb_mutation_uncertain` with `mutation_uncertain: true` and `recoverable: false`. Check the source before retrying; the change may already be applied. Sambee does not replay the write automatically.\n\nBackend and Companion watcher startup and native event failures trigger background recovery independently of index storage initialization. A successful scan does not clear an unavailable-watcher warning. Degraded verification remains active while monitoring is unavailable; recovered monitoring requires verification of the event gap.\n\nBackend status messages come from current conditions, in priority order: unavailable source, disk budget, storage initialization, stalled read, verification failure, update failure, observation loss, unavailable watcher, incomplete coverage, search-token rebuild, and continuous changes. Resolved conditions no longer leave old error text behind. A verification failure clears after a valid source-root check or after verification recovers. A successful read of an unrelated parent does not clear it. An update failure comes from the periodic loop and clears after a successful periodic iteration. A finished full pass clears observation loss, also when the pass has coverage issues; the coverage message then shows the remaining issue. Startup waiting, isolated local retries, and late first readiness do not themselves report source changes or observation loss. Actual watcher failures and observation gaps remain visible until their causes resolve.\n\nRecovery diagnostics use opaque source and lifecycle-generation IDs. Failure transitions record one sanitized cause; repeated failures use bounded summaries. Recovery logs omit private exception text and paths; third-party SMB payloads are not rendered. Scan summaries include duration even when a scan fails. Backend `directory_scan_finished` and `directory_retry_scheduled` events also include `invalidation_reason` and `stale_turns`, the count of consecutive stale turns with no completed parent.\n\nPass logs report source-owned I/O totals as per-pass differences: `smb_round_trips` for backend request groups and `native_opens` for companion directory-open attempts. See [Directory-Search Diagnostics](../../cross-cutting-systems/logging-and-localization/#directory-search-diagnostics) for the counter definitions and limits.\n\n### Quick-Bar Status Contract\n\nWork state, snapshot coverage, verification time, and monitoring health are separate. `monitoring_state` is `starting`, `healthy`, `recovering`, or `unavailable`. `retry_after_ms` is a relative delay from response receipt, not a timestamp. Missing or null fields mean that the server supplies no monitoring state or retry delay; they do not prove healthy monitoring.\n\n| Response or condition | Quick-bar behavior |\n|---|---|\n| Building or updating, without a retry delay | Show active work and check status again |\n| Paused work with a retry delay | Show the status message without an active-work spinner; wait before checking |\n| Empty data, uncertain coverage, or unavailable monitoring | Keep history available and continue bounded status checks |\n| Recoverable request failure | Keep accepted results for the same query, show failure, and retry |\n| Terminal or unsupported request failure | Stop automatic retries until reactivation or a source change |\n| Ready, healthy data without a warning | Stop periodic status checks |\n| Closed menu or hidden page | Stop periodic checks; reject stale responses when the query or source changes |\n\nStatus checks do not require a minimum search length. Empty-query activation initializes status and history. The directory provider limits retry delays to 1-60 seconds and uses a five-second fallback. Structured errors use `recoverable` and `retry_after_ms`; the client does not infer recovery rules from message text. Older responses without the shared search contract do not enable periodic status checks. Requests are bound to the current source, history client, storage capability revision, and request sequence. A replaced binding cannot publish old results, status, or retry timing.\n\n### Support Limits\n\nCompanion directory indexing supports Linux and Windows, not macOS. Drive visibility alone does not establish index support. Changes to native traversal or recovery require tests on the affected platform; cross-compilation does not validate runtime behavior.\n\n## Where to Continue\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): backend service ownership\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): uploads, moves, renames, and edit sessions\n- [Local-Drive and Save-Back Pipeline](../../companion-architecture/local-drive-and-save-back-pipeline/): companion file operations\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/#directory-search-diagnostics): directory-search diagnostics and privacy rules\n- [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/): test scope and repository gates\n\n## Validation Expectations\n\nSelect focused watcher, cache, storage, directory API, and SMB operation tests for the changed boundary. Verify source binding, partial failures, lost events, stale-read rejection, exact counts, and retained ownership through cancellation. For example:\n\n```bash\ncd backend\n.venv/bin/python -m pytest tests/test_directory_cache.py tests/test_directory_index_contract.py tests/test_directory_search.py tests/test_smb_backend.py\n.venv/bin/python -m mypy app\n```\n\nFor companion index changes, run the relevant Rust manager, storage, traversal, and handler tests. Add frontend checks when refresh, status, selection, or progressive result behavior changes.\n"}, "page_contents": {"0.7": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses two separate SMB2/SMB3 `CHANGE_NOTIFY` paths: one tells an open browser to refresh its directory listing; the other maintains the directory-search index. They have different subscription, event, and consistency rules.\n\n## Components\n\n| Component | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | Browser subscriptions, access checks, path-prefix mapping, and `directory_changed` delivery |\n| `backend/app/services/directory_monitor.py` | Shared per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | Per-connection index lifecycle, recursive directory-name notifications, and background verification |\n| `backend/app/services/directory_index.py` | SQLite storage, generations, search, and maintenance |\n| `backend/app/services/directory_traversal.py` | Handle-bound SMB enumeration, identity validation, and exact missing-child checks |\n| `companion/src-tauri/src/server/directory_manager.rs` | Local-drive index lifecycle, native observations, and background workers |\n| `backend/app/main.py` | Backend monitor and cache shutdown |\n\n## Browser Notifications\n\n### Subscriptions and Paths\n\n`DirectoryMonitor` shares one `MonitoredDirectory` per `connection_id:path`. The first subscriber starts it; the last unsubscribe stops it. A WebSocket disconnect must release that client's subscriptions.\n\nThe WebSocket layer uses user-facing paths. `ConnectionManager` applies the connection's `path_prefix` to obtain the native SMB path. Notification callbacks map that path back to the user-facing path before delivery. Subscription keys and native watch paths must not be used interchangeably.\n\n| Message | Example |\n|---|---|\n| Subscribe | `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n| Unsubscribe | `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n| Change notification | `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }` |\n\n### Events and Refreshes\n\nBrowser watchers observe file names, directory names, sizes, and last-write changes in the subscribed directory's immediate children. They do not watch the whole subtree. A deep write does not invalidate every ancestor listing, although metadata changes reported for an immediate child directory can trigger a refresh.\n\nThe browser retains loaded rows during automatic refresh, including an empty listing. It waits for an active listing request, combines notifications into one pending refresh, and starts at most one automatic refresh per second. Navigation and pane disposal cancel queued refreshes.\n\n`directory_changed` requests a new listing; it is not a file-difference protocol. See [File Browser and Navigation Model](../../frontend-architecture/file-browser-and-navigation-model/) for browser state and request handling.\n\n### Resource Ownership\n\nA monitor acquires its connection, session, tree, directory handle, and `FileSystemWatcher` in that order. Cleanup runs in reverse order, including after partial initialization.\n\nCancellation during startup retains the pending worker. When startup finishes, cleanup releases only the subscription acquired by that worker, not a replacement subscription. Shutdown rejects new monitor startup.\n\nTransient failures use capped exponential reconnect backoff with jitter. Recovery continues after fast retries are exhausted, while the subscription remains active. Deletion of the watched directory stops its monitor. A stopped monitor is not reused for new subscribers. Shutdown calls `shutdown_monitor()`; a worker that is still running retains its handles until it exits.\n\n## Directory-Index Consistency\n\nThe backend and companion maintain SQLite directory indexes through shared background managers, not per-request tree walks. Cold queries return status while initialization proceeds. Committed initial batches are searchable with partial coverage; result limits do not limit indexed coverage or exact match counts.\n\nThe index watcher observes directory-name changes recursively from the share root or configured prefix. Events drive parent reconciliation. Periodic full verification covers missed notifications; it must not become a full rescan on every navigation or query.\n\n### Generations and Observation Order\n\nFull verification updates the selected generation in place while retained data remains searchable. Interrupted first builds and active verification passes keep their rows, pass identity, and queued parents, including item issues and storage reopens. A completed full pass advances `last_verified_at_ms` even with item issues; incremental changes and queries do not. Each index retains one generation, with `building` for an initial build and `accepted` after completion.\n\nNon-root access failures, unsafe traversal, invalid names, and other item read errors do not stop a pass. The scanner skips an invalid name or completes a failed parent, then continues with readable siblings. A failed parent retains stored descendants, including batches already published during the current read. Acceptance retains the issue count and sets partial coverage. It clears the verification request and uses the regular verification interval, not a special item retry. Event loss still blocks acceptance and keeps coverage uncertain. Root, transport, authentication, resource-limit, and storage failures retain their retry and recovery rules.\n\nRead tokens and observation barriers reject stale results. Observed directory changes update the index and request verification, but they do not change coverage. Lost events or pending-observation queue overflow mark coverage uncertain and request verification without deleting retained data. Pass acceptance requires a valid root and no outstanding observations or reads that could invalidate the pass.\n\nDirectory rows, FTS entries, counts, issues, queued subtree work, and revision updates must remain transactionally consistent. Queries read results and metadata from one selected-generation transaction.\n\n### SMB Watcher Startup\n\nBackend initialization waits up to 10 seconds for the first watcher attempt before it probes the source root or scans directories. Success means that the first `CHANGE_NOTIFY` request has been sent and startup invalidation has completed, not just that the thread or connection has started. The wait is asynchronous and holds no scan slot, worker, coordinator lock, or generation lock.\n\nA connection failure, notification-start failure, or timeout permits fallback verification. Watcher retries continue in the background. A failed first attempt reports unavailable monitoring, not lost observations before monitoring started. The first-attempt result is separate from current monitoring readiness. Cancellation and shutdown remove the waiter and prevent a later scan from starting.\n\nIf the watcher first becomes ready during fallback verification, it changes the epoch. Pre-monitoring reads cannot commit. Verification resumes after the bounded observation retry; a valid root probe keeps retained results searchable. Normal successful startup captures its scan epoch after watcher setup and needs no startup retry.\n\n### SMB Barriers and Local Retries\n\nThe backend captures an epoch for each full pass without registering a pass-wide reader. A directory read depends on that directory, its direct children, and its ancestors. A barrier on a deeper descendant does not reject the ancestor listing. A root barrier rejects all content reads. Source-root availability probes check epoch and reader ownership, not directory-content barriers.\n\nObservations update the selected generation before their barriers retire. Barriers remain only while pending observations or older live parent reads need them. When retained barriers exceed their count or byte bound, they collapse to one current root barrier. Live content reads become stale, but the epoch does not change and pending hints remain available.\n\nA stale parent stays pending and moves to the queue tail in one transaction. Published child batches remain; deferral clears their staged snapshot names. The next read re-enumerates the parent and starts a fresh snapshot. Local stale reads, final-capture refusals, and transient parent errors do not invalidate unrelated completed work. Observation loss and exhausted read capacity cause bounded revalidation of retained completed parents. Other epoch changes do not restart completed parents.\n\nThe periodic loop checks due verification before incremental reconciliation. A full pass owns the selected generation's scan queue; separate reconciliation does not run during that pass. Completed buffered ancestors commit before descendants are selected, so deleted rows and refreshed FileIds take effect first. Stale reads use the one-second observation retry; source-wide failures keep the failure backoff. Quiet branches can progress, but a full pass cannot be guaranteed to finish while relevant directories keep changing.\n\nLarge reads store early snapshot names in `scan_snapshot_children`, owned by the pending parent queue row. This keeps memory bounded without separate per-child absence requests. The final diff considers both staged names and the final child batch. Direct-child changes still reject the read before parent completion. Failed parent reads preserve stored children instead of applying an incomplete deletion diff.\n\n### Parent Reconciliation\n\nBackground workers reconcile affected parents between full passes. Renames check both parents, and new directories trigger descendant reads. A completed listing under a held, validated parent drives the atomic child diff; an incomplete listing or access error cannot delete missing children. Streamed reads use the same disk-backed snapshot names as full passes. An item error records partial coverage, completes the parent, and retains its stored subtree. Source-wide failures and stale observations leave work pending. Reconciliation does not establish full verification or clear uncertain coverage.\n\nFile operations queue parent hints before dispatch and after actual worker completion, including failure. New mutation paths must preserve this rule. Cancellation must not release worker ownership early or change the original operation result when hint delivery fails.\n\n### Source Identity and Traversal\n\nCatalogue names are SHA-256 hashes of source boundary settings. SMB uses the connection ID, host, port, share, configured folder, and username. Passwords, display names, connection edit times, and runtime session IDs do not change the file name. Local sources use the configured root path and, for fixed, removable, and unknown drives, available volume serial or file-system UUID evidence. Network and virtual drives use the root path alone. Runtime session IDs remain diagnostic values.\n\nReused rows are unverified until a verification pass completes. An SMB reconnect binds new handles and invalidates unfinished reads. Queued child FileIds are expected read identities, not proof of storage continuity. SMB server GUIDs and volume metadata are diagnostic values. File IDs of zero or all ones are unavailable and are not queued as expected identities. Session and tree IDs are compared only within one connection.\n\n| Source | Traversal rules |\n|---|---|\n| SMB | No automatic DFS or symlink retries on compound reads; no-delete root handles; observed direct-parent reads only with healthy monitoring and a queued FileId; retained ancestors for safe fallback; connection-scoped session, tree, file-ID, and bound native-path checks |\n| Linux local drive | Retained directory descriptors, `openat2` with no-link, no-mount, and beneath-root resolution; component-by-component fallback when the syscall is unavailable; exact names and mount checks; kernel pseudo-filesystems and device-tree aliases excluded |\n| Windows local drive | No-delete bound-root handles, delete-sharing full-pass parent handles, 128-bit file IDs, volume and native-device paths; bounded enumeration and strict UTF-16 decoding |\n\nThe SMB boundary is logical: the configured share and folder. A configured subfolder is not an access-control boundary; the connection credentials can access the share. Storage mounted inside a share can be indexed; SMB does not promise physical-volume containment. DFS shares and reported reparse descendants remain excluded. Local traversal does not cross mounts. Windows junctions, name-surrogate redirections, cloud placeholders, and unknown reparse tags are excluded rather than followed. Missing optional volume metadata does not weaken these traversal checks.\n\nSMB full passes check the bound root at the start and end. Between these checks, a known parent can use a direct no-follow open without an ancestor chain only while the recursive folder-change watcher is ready and the epoch has no observation-loss or read-capacity invalidation. The opened FileId must match the queue, the handle must not report a reparse point, and the requested native path, session, and tree must match the binding. Root and reconciliation reads, missing-parent recovery, and exact child checks retain the safe ancestor chain. Parents without a queued FileId also use the safe path.\n\nObservation protects index correctness on the direct path. An ancestor event rejects affected reads before publication. Tokens remain live until grouped commits and check watcher readiness again at commit. A late event corrects already committed rows through the normal mutation path; the index is eventually consistent with the watcher delay. If monitoring is lost during a pass, active observed reads are deferred and the pass continues with safe reads. Observation loss requeues completed parents for revalidation, while coverage can remain uncertain. Root and non-compound scan handles retain no-delete sharing.\n\nDuring a full pass, safe reads reuse the pinned share and configured-root handles. Between full probes, local checks require connected handles, a non-DFS tree, the same connection object and server GUID, and unchanged session and tree IDs. Descendant ancestor chains and target FileAll identity checks remain. Closing a parent read does not close the root handles. A source-read failure requests a full root probe before a later read; versioned requests preserve failures that occur during a probe. Standalone reconciliation retains full root checks rather than relying on full-pass boundaries.\n\nSafe reads reuse cached `FsVolume` metadata across handles on the same live tree. The cache matches the tree and connection objects plus the session and tree IDs. A changed binding requires a new volume query. Unsupported optional volume information is cached for that binding; permission and transport failures are not cached. This cache does not replace root or parent verification.\n\n### SMB Compound Reads\n\nThe observed reader sends one related compound: `CREATE`, `QUERY_INFO(FileInternalInformation)`, two `QUERY_DIRECTORY` requests, and `CLOSE`. The first directory query restarts enumeration; the second continues it. End-of-directory responses complete a small or empty directory in one round trip. If both queries return data, the reader discards those partial results and opens the parent again through the existing enumeration loop.\n\nEach query buffer is bounded by the negotiated transaction size, the shared 1 MiB maximum, and available credits. A connection without multi-credit support uses at most 64 KiB. Full scans send up to `scan_pipeline_depth` compounds before receiving the oldest result. The shared default is eight parents. All reads use one worker and the root's retained connection; reused session and tree IDs cannot admit a replacement transport.\n\nBefore each pipeline send, the reader checks the credit window under the connection lock and leaves `scan_credit_reserve` credits, with a shared default of 16. Scan requests ask for credit growth until the window can support the configured depth. If a compound cannot fit, the worker receives the oldest outstanding parent first. With no outstanding reads, it can send one bounded credit-growth echo per queue page, including when the window starts at one credit. If the server does not grant enough credits, the reader uses the existing loop instead.\n\nThe pool creates a `ScanCreditConnection` before transport setup and lets `smbclient` register its session with the configured authentication and encryption policy. Its reentrant sequence lock covers the full scan credit check and compound send. Ordinary browse sends use the same lock, so they cannot consume credits between the scan check and the library's per-message allocations. The check uses the library's negotiated credit charges, with a minimum of one credit per message. If the full compound and reserve do not fit, admission changes no sequence numbers or outstanding requests. The lock is released before receiving responses.\n\nConnections without this atomic-admission method use the existing loop instead of an unprotected pipeline send. A failed compound send still retires and aborts that connection generation rather than reusing uncertain request state.\n\nThe loop also adapts its query buffer before each request. It uses the negotiated transaction size and the shared 1 MiB maximum, then limits the size to the current credit budget. It leaves the browse reserve where possible, but retains a one-credit query when the window is small. Connections without multi-credit support use at most 64 KiB. These size estimates do not add atomic admission to loop reads; the whole-compound lock applies to pipeline sends.\n\nCompound handles allow read, write, and delete sharing because they open and close within the same request group. The reader disables client-side symlink retries and drains responses after a parent error. Each in-flight read has a deadline measured from submission. A timeout, including during cleanup after watcher loss, defers unfinished parents and retires the connection generation through the pool's abort path. A mutation barrier on one parent defers only that parent; unrelated valid results remain eligible for grouped commit in queue order. Watcher loss defers all outstanding observed reads before the pass continues with safe traversal.\n\nFileId mismatches, reparse attributes, malformed responses, and listings that make no progress cannot publish children. Missing-path and access-denied responses retain their existing cache error handling. Buffered results still check observation and local root binding during enumeration and before commit. Exact child checks reopen the safe retained-ancestor reader.\n\nThe drive browser and local index share one classifier. USB, SD, MMC, and hot-plug disks are removable even when Windows reports a fixed drive. Failed classification uses the unknown class. Fixed drives select another index only when available volume serial or UUID evidence changes. Removable and unknown drives also replace the current generation when available label, file-system type, or total-capacity evidence changes. Generation replacement selects the new generation and deletes the old one in one transaction. Unchanged volume evidence does not rewrite source metadata. Missing evidence and drive-class changes alone do not replace data. Windows uses the 64-bit serial from `FILE_ID_INFO`, including zero. Local file IDs are session-scoped checks, not replacement signals.\n\nVolume evidence is checked again when the root binds. An unmounted Linux source stays unavailable instead of indexing its mount-point folder. Linux mount checks use descriptor-bound `statx` mount IDs with `/proc/self/fdinfo` as a fallback. A missing mount-boundary capability stops that source until Companion restarts. Idle removable sources without active work or a watcher release their root handles. Windows removal notifications pause source work and release handles before removal is allowed.\n\nDepth and path-length bounds are defined in `shared/directory-index/contract.json`. Excluded descendants produce partial coverage while readable branches continue.\n\nLinux enumeration uses `d_type` to skip regular files without a metadata call. Unknown entry types use a no-follow metadata check. A no-follow `statx` checks each directory child's inode and mount without opening the child. Missing statx fields use the descriptor fallback. Windows enumeration uses a 1 MiB buffer and validates names, attributes, reparse tags, and full 128-bit FileIds from directory records without opening each child.\n\nA native scan uses one `NativeParent` read through enumeration, batch validation, issue handling, and parent completion. It checks the queued identity before processing children and keeps the observation token checks before writes. Linux retains the parent descriptor and gives `fdopendir` a duplicate, so enumeration cannot close the original. Descriptor checks reject a deleted parent without reopening its path. If the watcher is missing, failed, or not yet ready, Linux also checks the root-relative parent identity before each child batch and final parent completion, including parallel full-pass and reconciliation reads. A healthy watcher adds no parent opens at these boundaries. Windows full-pass reads use FileId opens, relative no-reparse opens, or the checked ancestor fallback. Non-root scan handles permit read, write, and delete sharing. The bound root and strict standalone reads keep no-delete sharing. Identity and native-path checks reject a moved parent before publication. Missing-parent recovery uses exact child lookups under the retained parent.\n\nFull passes read independent parents with at most four native worker threads, defined by `scan_read_parallelism`. A bounded channel sends child batches, issues, and completion to the scan thread; workers never write the index. Each read retains its handle and observation token until publication or discard. Queued ancestors finish and commit before their descendants start, so changed FileIds reach later reads. Cancellation and storage failure stop new jobs, drain ownership, and join all workers.\n\nBackend initialization withholds rows until a handle-bound root probe succeeds. Root failure returns HTTP 503 without deleting accepted data. Descendant access denial produces partial coverage instead. Late results cannot restore an invalidated source.\n\n### SQLite Storage\n\n| Runtime | Location and driver |\n|---|---|\n| Backend | `data/directory_cache/sqlite/`, or `sqlite/` below `directory_cache_location`; standard Python `sqlite3` with Debian system SQLite |\n| Companion | `directory-index/sqlite/` in the OS-user cache directory; bundled Rust SQLite binding |\n\nIndexes are disposable directory data, separate from recent history. Stored source metadata excludes passwords. `shared/directory-index/` owns the schema, search normalization, validation rules, and contract fixtures.\n\nSchema version 5 retains nullable FileIds in `scan_queue`: eight bytes for SMB and Linux, and 16 bytes for Windows. Root and observed-parent entries can omit an identity. Child identities commit with directory rows and survive a deferred read or reopen. Full passes and reconciliation refresh existing queue rows when a parent listing supplies a different non-null identity. Reconciliation does not insert a job for an existing child that has no queue row. A change from a known identity requeues completed child work; a change from an unknown identity keeps its processed state. Unchanged identities cause no queue writes. Readers compare a queued identity before publishing children. Companion can first commit a fresh buffered parent listing to update that identity. A confirmed mismatch is an unsafe item issue.\n\nDirectory rows have a nullable `parent_id` and the `directories_parent(generation_id, parent_id)` index. Stored links must identify an immediate parent in the same generation. Deletes cascade to linked descendants, their FTS entries, and their queue rows. Adds and moves maintain parent links. Both scanners diff complete and streamed parent snapshots and finish their queue rows in one transaction without rewriting unchanged directory or FTS rows. Early batches store their names in `scan_snapshot_children`. Final completion removes absent linked subtrees, clears staged names, and completes the parent atomically. Failed parents suppress deletions. Old-schema indexes rebuild through disposable-cache recovery; recent history is not changed.\n\nItem issue counts belong to the producer's observation token. Full passes buffer these counts until the completed parent snapshot commits; reconciliation commits them with the final parent snapshot. Early incomplete child batches retain the pending counts. A stale token discards them and leaves its parent pending. Counts aggregate by issue code in the parent transaction, so coverage, revision, directory changes, and parent completion roll back together if a write fails. Buffered issue payloads count toward the group byte bound.\n\nBoth source managers retain a process-local sample of affected parent paths and issue codes after successful parent commits. The sample uses the shared `max_logged_scan_issues_per_pass` bound, removes resolved parent entries after clean reads, and resets for a new full pass. Successful delete observations and parent snapshots also remove samples for deleted subtrees; failed database writes retain the samples. It is not persisted or added to the index schema. Ordinary search responses expose `issue_details_available`; `include_issue_details=true` additionally returns `issue_details` and `issue_details_incomplete`. These details use the same source authorization as directory search. A listed parent can identify a location containing an unreadable child name rather than an unreadable parent itself.\n\nThe selected generation records `scan_pass_id` and `scan_active`. A fresh verification resets its queue completion flags and starts a new pass; an interrupted active pass resumes without that reset. A completed pass keeps the selected generation ID. The clean-shutdown marker is cleared on open and set only after a clean, transaction-free close with ready search tokens. A clean reopen skips SQLite `quick_check` and the FTS integrity command when the FTS schema is intact. An unclean reopen runs both checks. Schema, foreign-key, generation, and storage-binding validation still run on every open. Reopen retains valid streamed snapshot names; the first restarted batch replaces them. Invalid names or snapshots owned by completed parents trigger disposable-cache recovery.\n\nBoth stores use WAL and `synchronous=NORMAL`. The index is a verified cache, not the source of directory data. A power failure can lose recent cache commits; interrupted or uncommitted work remains pending for verification. Writes, checkpoints, maintenance, and close are serialized through the writer. Queries use read-only connections and explicit transactions. Both runtimes reuse isolated read connections and check their storage binding before each query. Query cancellation handlers are cleared before reuse. Storage leases remain held until admitted readers and workers finish; active database families cannot be evicted.\n\nScan writes use bounded parent groups. Content-changing groups have a 250 ms maximum wait and a 1,000-parent cap. Bookkeeping-only groups have a 1 s maximum wait and a 20,000-parent cap. Each interval starts with the first parent, not the previous commit. Both groups commit early at the parent cap or the shared byte bound; parent names count toward that bound. Independent work pages do not force a commit. Ancestor dependencies, error transitions, and pass completion can require an earlier commit. Each completed parent keeps its observation token and barriers until commit, but no longer uses active-reader capacity. The next page excludes completed buffered parents. A stale parent remains pending; valid parents in the group can commit. Large parent reads can publish child batches before the parent is complete.\n\nReconciliation uses the same adaptive groups as full passes without advancing the full-verification clock. Queue paths and FileIds are read in pages, and buffered completed parents are excluded from later pages. Ancestors commit before queued descendants start. Backend reconciliation uses the page's FileIds and keeps its per-parent worker deadline. Native reconciliation uses the bounded worker scheduler but retains strict root and parent opens, rather than full-pass fast opens. Early snapshots, issue counts, stale deferral, and ownership cleanup use the reconciliation generation checks. Status snapshots refresh after group commits.\n\nEmpty-query status uses committed metadata snapshots in memory. It does not open SQLite connections or run a directory query. The optional `scan_progress` response contains the phase, completed and queued parent counts, directory count, and start timestamp. Each group commit refreshes progress. The frontend shows active build or update progress before uncertain coverage.\n\nThe `cache_state` value `opening` identifies index initialization before scanning. The quick bar hides this status but continues polling. Errors and recovery messages remain visible. Once scanning starts, build or update progress replaces the opening state. A build shows `Indexing...` until its directory count is positive; zero is not shown as a directory result.\n\nStorage must be private and local. Opens and cleanup validate directory ownership, file identity, and aliases. Do not write to managed databases externally or weaken these checks to permit a path-only fallback.\n\n### Resource Controls\n\nWorker counts, batches, and observation queues are bounded by the shared contract. Disk growth requires headroom and free-space admission. Native full-pass and reconciliation groups share one disk reservation for their writes. Ordinary admission reuses its free-space sample for the final reservation check while holding the accounting lock. If cleanup runs, admission takes a fresh sample before it reserves space. Outstanding reservations remain part of both budget and physical-space checks. Maintenance yields to active work.\n\nAutomatic full passes have a minimum spacing of 30 seconds, defined in the shared contract. Requests cannot bypass this limit or failure backoff. Interrupted passes retain completed directory work and item issues. After an observation gap, retained directory reads are revalidated in bounded batches before pass acceptance. Parent reconciliation does not start a new full pass or advance the full-verification clock.\n\nPolicy defaults and ranges belong to `shared/directory-index/contract.json`. A lower budget may pause growth but must not trim active data. Eviction applies only to inactive, unowned indexes. Disk and cache settings are not hard filesystem or process-memory ceilings.\n\nSee [Directory-Index Policy Delivery](../../companion-architecture/local-drive-and-save-back-pipeline/#directory-index-policy-delivery) for Companion ownership and [Manage Directory Search](../../../admin-guide/operations-and-maintenance/manage-directory-search/) for administration.\n\n### Recovery and Shutdown\n\nStartup validates source identity and application consistency before exposing rows. Damaged search tokens rebuild from validated directory rows. Replacement is restricted to recognized invalid index data; permission, capacity, busy-storage, and general I/O failures must not trigger discard.\n\nFailures use bounded retries. Requests must not bypass retry deadlines. Access updates only the last-access time; an idle gap does not invalidate observations or make a running source unavailable. Idle sources release resources only when no worker, reader, or queued scan work remains. Released sources revalidate the root on reuse. Shutdown waits for admitted work before closing storage and root ownership, even when a request has been cancelled.\n\nFor the backend, scan work waits for both the resource-failure and observation-retry gates. The scan delay is therefore the later active deadline. `retry_after_ms` reports the earlier of that scan deadline and the next watcher retry. Status requests and searches do not move these deadlines. A local stale read uses the one-second observation retry, not a new failure backoff or a new full-pass interval.\n\nBackend and Companion epoch invalidations record a diagnostic reason: `watcher_start`, `observation_loss`, `source_rebind`, `read_capacity`, `stalled_read`, or `lifecycle`. These cover first notification setup, lost observations, source rebinding, exhausted read admission, stalled workers, and lifecycle changes. All reasons request verification. All reasons except `stalled_read` also mark coverage uncertain, because they can lose source events. A stalled read loses no events, so the next accepted pass can verify the index. Epoch and ownership checks reject stale work. The SMB observed path also stays disabled in an epoch with observation loss or exhausted read capacity, even after the queue-revalidation flag is consumed. Each invalidation logs its reason and a counter at INFO, including repeated reasons. Pass start and finish events also use INFO. Finish events include parent and directory counts, group commits, duration, and an abort reason when the pass fails.\n\nIndex recovery does not reset a shared SMB connection or remove recent-directory history. A source binding mismatch pauses publication, re-binds source handles, and schedules verification. Source and storage failures are not evidence that a directory was deleted.\n\nSMB setup runs outside the shared pool lock. Concurrent requests share setup for the same private cache. The pool bounds admitted work, setup tasks, and retained connection generations, both per source and across the process. A retired generation keeps its own cache until its workers and cleanup finish; replacement requests use a separate cache. Capacity failures return retry information rather than enter an unbounded queue. Shutdown stops new admission. Writes are not replayed automatically.\n\nA caller timeout or cancellation does not itself stop a blocking SMB operation. Reader handles, connection leases, and worker permits remain owned until actual completion. Late successful opens are closed before their leases are released.\n\nAn operation deadline retires its connection generation and requests one pool-owned transport abort through public `Connection.disconnect(close=False)`. The abort runs outside the event loop and pool lock, uses a snapshot of that generation's connections, and does not send session logoff requests or touch replacement connections. Ordinary caller cancellation retains work without aborting unrelated operations on the shared generation. Long-lived watcher subscriptions use their own lifecycle, not ordinary operation deadlines.\n\nPublic abort wakes blocked receive requests in the installed client. It cannot provide a universal operation deadline: disconnect shares a lock with socket send and can remain blocked behind a send. Abort work retains capacity until it exits. If workers cannot finish, admission remains bounded and requests return capacity errors. Wait before retrying; restart the backend service if retained work continues to occupy capacity.\n\nA mutation interrupted by abort, or whose caller deadline expires after dispatch, has uncertain completion. The API reports `smb_mutation_uncertain` with `mutation_uncertain: true` and `recoverable: false`. Check the source before retrying; the change may already be applied. Sambee does not replay the write automatically.\n\nBackend and Companion watcher startup and native event failures trigger background recovery independently of index storage initialization. A successful scan does not clear an unavailable-watcher warning. Degraded verification remains active while monitoring is unavailable; recovered monitoring requires verification of the event gap.\n\nBackend status messages come from current conditions, in priority order: unavailable source, disk budget, storage initialization, stalled read, verification failure, update failure, observation loss, unavailable watcher, incomplete coverage, search-token rebuild, and continuous changes. Resolved conditions no longer leave old error text behind. A verification failure clears after a valid source-root check or after verification recovers. A successful read of an unrelated parent does not clear it. An update failure comes from the periodic loop and clears after a successful periodic iteration. A finished full pass clears observation loss, also when the pass has coverage issues; the coverage message then shows the remaining issue. Startup waiting, isolated local retries, and late first readiness do not themselves report source changes or observation loss. Actual watcher failures and observation gaps remain visible until their causes resolve.\n\nRecovery diagnostics use opaque source and lifecycle-generation IDs. Failure transitions record one sanitized cause; repeated failures use bounded summaries. Recovery logs omit private exception text and paths; third-party SMB payloads are not rendered. Scan summaries include duration even when a scan fails. Backend `directory_scan_finished` and `directory_retry_scheduled` events also include `invalidation_reason` and `stale_turns`, the count of consecutive stale turns with no completed parent.\n\nPass logs report source-owned I/O totals as per-pass differences: `smb_round_trips` for backend request groups and `native_opens` for companion directory-open attempts. See [Directory-Search Diagnostics](../../cross-cutting-systems/logging-and-localization/#directory-search-diagnostics) for the counter definitions and limits.\n\n### Quick-Bar Status Contract\n\nWork state, snapshot coverage, verification time, and monitoring health are separate. `monitoring_state` is `starting`, `healthy`, `recovering`, or `unavailable`. `retry_after_ms` is a relative delay from response receipt, not a timestamp. Missing or null fields mean that the server supplies no monitoring state or retry delay; they do not prove healthy monitoring.\n\n| Response or condition | Quick-bar behavior |\n|---|---|\n| Building or updating, without a retry delay | Show active work and check status again |\n| Paused work with a retry delay | Show the status message without an active-work spinner; wait before checking |\n| Empty data, uncertain coverage, or unavailable monitoring | Keep history available and continue bounded status checks |\n| Recoverable request failure | Keep accepted results for the same query, show failure, and retry |\n| Terminal or unsupported request failure | Stop automatic retries until reactivation or a source change |\n| Ready, healthy data without a warning | Stop periodic status checks |\n| Closed menu or hidden page | Stop periodic checks; reject stale responses when the query or source changes |\n\nStatus checks do not require a minimum search length. Empty-query activation initializes status and history. The directory provider limits retry delays to 1-60 seconds and uses a five-second fallback. Structured errors use `recoverable` and `retry_after_ms`; the client does not infer recovery rules from message text. Older responses without the shared search contract do not enable periodic status checks. Requests are bound to the current source, history client, storage capability revision, and request sequence. A replaced binding cannot publish old results, status, or retry timing.\n\n### Support Limits\n\nCompanion directory indexing supports Linux and Windows, not macOS. Drive visibility alone does not establish index support. Changes to native traversal or recovery require tests on the affected platform; cross-compilation does not validate runtime behavior.\n\n## Where to Continue\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): backend service ownership\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): uploads, moves, renames, and edit sessions\n- [Local-Drive and Save-Back Pipeline](../../companion-architecture/local-drive-and-save-back-pipeline/): companion file operations\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/#directory-search-diagnostics): directory-search diagnostics and privacy rules\n- [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/): test scope and repository gates\n\n## Validation Expectations\n\nSelect focused watcher, cache, storage, directory API, and SMB operation tests for the changed boundary. Verify source binding, partial failures, lost events, stale-read rejection, exact counts, and retained ownership through cancellation. For example:\n\n```bash\ncd backend\n.venv/bin/python -m pytest tests/test_directory_cache.py tests/test_directory_index_contract.py tests/test_directory_search.py tests/test_smb_backend.py\n.venv/bin/python -m mypy app\n```\n\nFor companion index changes, run the relevant Rust manager, storage, traversal, and handler tests. Add frontend checks when refresh, status, selection, or progressive result behavior changes.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/file-operations-and-edit-locking", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "file-operations-and-edit-locking", "title": "File Operations And Edit Locking", "path": "developer-guide/backend-architecture/file-operations-and-edit-locking", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.8": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.9": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "1.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "2.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.8": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.9": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "1.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "2.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n### Storage Timestamps\n\nStorage metadata must use timezone-aware UTC timestamps. Directory listings, path-based metadata lookup, and metadata read from an open file handle must use the same time basis. Convert Unix timestamps with an explicit UTC timezone, not the backend process timezone.\n\nSource-change checks, overwrite-older decisions, and modification-time preservation depend on this rule. A local timestamp without timezone information can produce a false source-change error or an incorrect conflict decision when the backend container uses a non-UTC timezone.\n\nTest metadata conversion with UTC and a non-UTC process timezone. Include standard time and daylight saving time.\n\n### API Error Details\n\nPreserve the error code and message when an operation passes through a relay. Read the API's error envelope: a response with top-level `code` and `message` fields must not lose its message because a caller expects a legacy `detail` field. Keep legacy error support where the caller serves both API formats. Use a specific fallback when the response has no usable message.\n\nShow the operation's error message in its dialog. Log the response status, code, and message without the full HTTP client error object, which can contain authentication headers or operation tokens.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/frontend-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "frontend-architecture", "title": "Frontend Architecture", "path": "developer-guide/frontend-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "0.8": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "0.9": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "1.0": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "2.0": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/frontend-overview", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "frontend-overview", "title": "Frontend Overview", "path": "developer-guide/frontend-architecture/frontend-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.8": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.9": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "1.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "2.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.8": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.9": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "1.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "2.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/theming-system-and-theme-selection", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "theming-system-and-theme-selection", "title": "Theming System And Theme Selection", "path": "developer-guide/frontend-architecture/theming-system-and-theme-selection", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 5}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 53, "diff_removed": 263}}, "content_versions": {"0.7": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.8": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.9": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "1.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "2.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee has two built-in themes (`sambee-light` and `sambee-dark`), user-owned themes, and administrator-managed site themes. Built-in IDs stay stable across upgrades, so updating their palettes doesn't change anyone's selection.\n\n## Theme Data\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | Palette types and editor field labels |\n| `frontend/src/theme/themes.ts` | Built-in definitions with stable IDs |\n| `frontend/src/theme/themeDefinition.ts` | Editable color catalog, hex checks, and versioned import/export |\n| `frontend/src/theme/resolveSyntaxTheme.ts` | Non-mutating legacy syntax defaults and strict supplied-palette validation |\n| `frontend/src/theme/syntaxStyles.ts` | Shared token classes and locally inherited syntax variables |\n| `frontend/src/theme/palette.ts` | Shared effective palette for the app |\n| `frontend/src/theme/viewerStyles.ts` | Viewer and Markdown document surfaces |\n| `frontend/src/theme/ThemeContext.tsx` | Registry refresh and Material UI theme |\n| `frontend/src/pages/PreferencesSettings.tsx` | Selection grid and selected-theme actions |\n| `frontend/src/components/Settings/ThemeEditorDialog.tsx` | Responsive theme editor |\n| `backend/app/api/themes.py` | Validated theme operations and site default |\n\nEach editable theme has its own server row with a globally unique ID, scope, owner (for user themes), and version. Full built-in palettes remain in frontend code. The built-in `id`, `mode`, and `primary.main` fields live in `shared/companion-themes.json` and are reused by the backend and frontend. A new theme ID is assigned by the server; an ID in an imported file does not claim or replace a stored theme.\n\nColors use `#RRGGBB` or `#RRGGBBAA`; the server normalizes valid hex to uppercase. The role catalog includes primary, backgrounds, text, selection, links, viewer surfaces, Markdown document surfaces, syntax, search highlights, and alerts. File-type icons aren't theme roles. Derived colors such as scrollbar shades, focus rings, and `background.paper` compatibility aren't editor fields. Keyboard focus rings follow the theme's primary text color: 57% opacity in light mode and 94% in dark mode. Changing that text color changes the focus color too, including in copied themes; legacy saved focus colors are ignored. Choose primary text that remains readable against the theme's surfaces.\n\nEvery existing editable role remains required. The additive `components.syntax` group has eight roles: `keyword`, `string`, `number`, `comment`, `type`, `function`, `operator`, and `punctuation`. If the entire group is absent from a stored definition or version-1 import, the frontend resolves the matching built-in light/dark palette without mutating or saving the original. A supplied group must contain exactly all eight valid colors; partial groups, nulls, unknown keys, and invalid colors are rejected by both frontend and backend. Save, copy, and export include the resolved group through the existing API and version-1 envelope. No database migration or separate syntax preferences are needed. Older application releases may reject these newer exports.\n\n## Selection And Defaults\n\n`SambeeThemeProvider` combines built-ins with the current user's themes and shared site themes from `GET /api/themes`. The per-user selection is saved separately through `appearance.theme_id` in `PUT /api/auth/me/settings`. The backend reports whether that value is an explicit override.\n\nA user without an override follows the site default (initially `sambee-light`). A user who explicitly chooses `sambee-light` keeps that ID even if an administrator changes the site default. The selected ID points at a theme definition, never at a frozen copy of a built-in. The provider refreshes shared themes, the default, and user settings on initial load, tab focus, visibility return, and local writes. It discards out-of-date responses when the account changes.\n\nAppearance settings display Your themes, Site themes, then Built-in themes. Clicking a tile or selecting its radio applies the theme and creates an explicit user override, even when it already matches the site default. Moving focus between radios doesn't change the applied theme or the target of Copy, Edit, Delete, and Set as default. The Default chip is distinct from the selected radio. Copy keeps writable themes in their group and copies read-only themes into Your themes without applying the copy. Editing read-only themes permits inspection and Save copy, but not Save. Only an administrator can save or delete site themes or make a built-in or site theme the default.\n\n## Companion Theme Delivery\n\nCompanion follows the active user's resolved theme on the authoritative paired server through [Shared Settings Delivery](../../companion-architecture/browser-to-companion-trust-model/#shared-settings-delivery). The backend resolves built-in and stored themes and the site default. It hashes the small Companion payload independently of directory policy. Persisted theme changes trigger synchronization; unchanged digests are no-ops. Native `ThemeState` broadcasts to existing windows and supplies the current theme to new windows. Routine paired delivery must not use a theme in a deep-link URI; that path is only a bootstrap fallback and cannot replace managed settings.\n\n## Editing And Persistence\n\nThe editor uses a responsive dialog with collapsible color groups. A swatch opens an alpha-aware picker and each color has an editable hex field. Invalid text stays in the field without changing the valid draft. Changes in the editor aren't applied to the app until Save succeeds; Cancel discards the draft. Import replaces only the draft after validating a versioned JSON definition, and Export writes the same format.\n\n`POST /api/themes` creates a theme. Save copy opens a destination menu with Your themes for everyone and Site themes for administrators. It always creates a new theme in the chosen group without changing the applied selection. If its name already exists in that group, the editor adds ` (copy)` or a numbered copy suffix. Save updates only the opened theme in its existing group and cannot create a copy. `PUT /api/themes/{id}` and `DELETE /api/themes/{id}?version=...` require the version read by the client; a stale version returns HTTP 409. The server checks ownership, admin permissions, names, IDs, and palette completeness before committing. Bulk writes to `appearance.custom_themes` are no longer supported. Legacy syntax compatibility is limited to an entirely absent syntax group; it doesn't repair incomplete older definitions.\n\nDeleting a theme clears explicit selections referencing it. If it was the site default, that setting is cleared too; users without an override then fall back to Sambee light. An explicit selection of another theme is unaffected.\n\n## Component Guidance\n\nPrefer the effective colors in `resolveThemePalette` and the MUI palette to hard-coded surfaces. `background.default` is the normal application surface; `background.paper` resolves to the same value for MUI compatibility. Dark chrome and dialogs use the editable `background.chrome` role. Markdown code, tables, blockquotes, and heading borders use the built-in theme's explicit document colors.\n\nViewer toolbar foreground variants, scrollbars, and subdued states can still derive opacity-adjusted values from their source color. Keep fixed colors for assets and file-type icons separate from the editor palette.\n\n## Shared Syntax Highlighting\n\nText viewing/editing, Markdown source and rendered Markdown fences share the CodeMirror language registry and tag mapping in `codeMirrorHighlightingCore.ts`. `syntaxHighlighting.ts` defines application-owned language IDs, UTF-16 token ranges, categories and explicit results that indicate plain text. Native editors and the syntax worker reuse that implementation. Fence aliases resolve to existing lazy grammars, including `mssql` to MS SQL and `mariadb` to MariaDB SQL. A `.sql` filename continues to select standard SQL; unknown fence labels aren't guessed.\n\nThe live Markdown viewer collects exact code occurrences from ReactMarkdown's existing AST, without another collection parse or embedded editors. A dedicated cancellable worker prepares syntax sequentially with acknowledged source chunks of at most 16,384 UTF-16 units and result pages of at most 512 ranges. Blocks above 100,000 UTF-16 units stay plain text. Nested Markdown fences use the configured Markdown parser, up to four Markdown levels including the outer block. Unknown, unlabelled and explicit plain-text fences remain neutral. A nested grammar load failure, or a parser error during static fence startup or advancement, leaves only the failed fence plain while retaining enclosing Markdown structure and successful siblings. The static adapter doesn't mutate cached grammars or retry parsing; later fences and preparations can still succeed. Closing during a pending grammar load terminates the generation's worker; reopening starts a fresh preparation. Cancellation still propagates, and exceeding the nesting limit intentionally keeps the whole outer block plain without suppressing unrelated blocks. There's no aggregate document-length or block-count cutoff. The pre-app browser capability gate requires the Web Worker API; Worker-less app operation isn't supported. The helper's defensive main-thread fallback isn't a supported browser mode or a responsiveness guarantee.\n\nEach preview generation owns cancellation and stale-result guards. After all requested blocks finish, the viewer paints at most 4,000 viewport syntax ranges through CSS Highlights. Vertical and horizontal clipping avoid publishing off-screen token ranges; scrolling, viewport resize, image loads and font readiness refresh presentation. Publication doesn't replace text nodes or insert token spans, preserving native text, whitespace, selection and the cached preview-search index. Missing highlight/visibility capabilities leave syntax plain instead of falling back to token DOM mutation. Disposal removes owned highlights, style, observers, listeners and queued frames. First visible syntax, complete preparation, memory and native interaction acceptance remain separate rollout gates; see [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/).\n\nThe existing theme provider installs stable application token rules once. Viewer/editor surfaces publish locally inherited CSS variables from the resolved MUI syntax palette, so changing theme colors doesn't require reparsing code or replacing token DOM. Identifiers and neutral code inherit the existing code foreground. Markdown source headings and structural markers use `keyword`; links use the existing link role; inline code uses the existing code foreground. Emphasis, strong text, and strikethrough change only their corresponding semantic treatment, not source font sizes or line geometry. Embedded code uses code categories, not Markdown prose styling.\n\nThe shared mapping also preserves built-ins, properties and keys, booleans, null, regular expressions, escapes, and metadata/directives when the grammar supplies those tags. `TOKEN_COLOR_ROLES` maps these categories to the existing eight syntax colors: built-ins use `function`; properties and regular expressions use `type`; booleans, null, and metadata use `keyword`; escapes use `operator`. Editors and rendered fences share this mapping without another parse or a theme schema change. Built-in names aren't necessarily commands, and grammar classifications vary: PowerShell variables and bare words can both remain neutral identifiers. There are no language-specific classification overrides.\n\nSearch matches use the viewer text foreground instead of syntax colors so matched keywords remain readable against their highlight backgrounds. Source editors apply that foreground to the match and its nested tokens. Preview search inherits `--sambee-search-foreground` from its own viewer; syntax highlights have priority -1, ordinary search highlights 0, and the current match 1. The shared search-color helper preserves the configured hues and uses 30%/36% opacity for ordinary/current matches in light mode and 40%/44% in dark mode. Custom theme validation checks color format and completeness, not contrast; choose text, syntax and surface colors that remain readable after alpha blending.\n\nTheme updates and lazy grammar completion preserve native selection, the active search match and both scroll axes on all four surfaces. Theme changes don't restart syntax preparation or renormalize unchanged Markdown. Late grammar completion can update editor token spans, while preview publication retains its original text nodes. These state guarantees don't establish scrolling performance, native clipboard behavior or close/navigation acceptance.\n\nReplacing an editor doesn't require replacing static highlighting. Replacing the engine requires preserving the application's requirements for token ranges and highlighting results, aliases where supported, and viewer lifecycle. Classification parity with a different engine isn't automatic. Removing CodeMirror entirely also requires migrating native editor integrations such as commands, autocomplete, and tables.\n\n## Verification\n\nRun focused theme tests and the project checks after changing the palette, API, or editor:\n\n```bash\ncd frontend \u0026\u0026 npm run test -- src/theme/__tests__ src/pages/__tests__/PreferencesSettings.test.tsx\ncd frontend \u0026\u0026 npm run build \u0026\u0026 npm run lint\ncd backend \u0026\u0026 .venv/bin/python -m pytest tests/test_user_settings.py\n```\n\nCheck the Appearance grid and editor on a phone and desktop in both built-in modes. Verify selection and saved-theme refresh after focus, color picker keyboard use and placement, alpha values and export, Cancel without applying the draft, and stale-save feedback.\n\nFor the production theme-dialog browser regressions, build the frontend first and keep the existing frontend/backend dev servers running. From `frontend/`, run:\n\n```bash\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production syntax theme dialog' --workers=1\n```\n\nThe suite serves built assets and intercepts theme APIs at `http://localhost:3000/browse/smb/demo`; it doesn't change stored themes. Chromium and Firefox cover save/cancel/copy, validation focus, personal/site/built-in permissions, alpha values, unchanged selection after copying, and rejected-save feedback at 1543x900 and 390x600. Narrow desktop viewports don't replace testing on a physical phone or with assistive technology.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.8": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.9": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "1.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "2.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee has two built-in themes (`sambee-light` and `sambee-dark`), user-owned themes, and administrator-managed site themes. Built-in IDs stay stable across upgrades, so updating their palettes doesn't change anyone's selection.\n\n## Theme Data\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | Palette types and editor field labels |\n| `frontend/src/theme/themes.ts` | Built-in definitions with stable IDs |\n| `frontend/src/theme/themeDefinition.ts` | Editable color catalog, hex checks, and versioned import/export |\n| `frontend/src/theme/resolveSyntaxTheme.ts` | Non-mutating legacy syntax defaults and strict supplied-palette validation |\n| `frontend/src/theme/syntaxStyles.ts` | Shared token classes and locally inherited syntax variables |\n| `frontend/src/theme/palette.ts` | Shared effective palette for the app |\n| `frontend/src/theme/viewerStyles.ts` | Viewer and Markdown document surfaces |\n| `frontend/src/theme/ThemeContext.tsx` | Registry refresh and Material UI theme |\n| `frontend/src/pages/PreferencesSettings.tsx` | Selection grid and selected-theme actions |\n| `frontend/src/components/Settings/ThemeEditorDialog.tsx` | Responsive theme editor |\n| `backend/app/api/themes.py` | Validated theme operations and site default |\n\nEach editable theme has its own server row with a globally unique ID, scope, owner (for user themes), and version. Full built-in palettes remain in frontend code. The built-in `id`, `mode`, and `primary.main` fields live in `shared/companion-themes.json` and are reused by the backend and frontend. A new theme ID is assigned by the server; an ID in an imported file does not claim or replace a stored theme.\n\nColors use `#RRGGBB` or `#RRGGBBAA`; the server normalizes valid hex to uppercase. The role catalog includes primary, backgrounds, text, selection, links, viewer surfaces, Markdown document surfaces, syntax, search highlights, and alerts. File-type icons aren't theme roles. Derived colors such as scrollbar shades, focus rings, and `background.paper` compatibility aren't editor fields. Keyboard focus rings follow the theme's primary text color: 57% opacity in light mode and 94% in dark mode. Changing that text color changes the focus color too, including in copied themes; legacy saved focus colors are ignored. Choose primary text that remains readable against the theme's surfaces.\n\nEvery existing editable role remains required. The additive `components.syntax` group has eight roles: `keyword`, `string`, `number`, `comment`, `type`, `function`, `operator`, and `punctuation`. If the entire group is absent from a stored definition or version-1 import, the frontend resolves the matching built-in light/dark palette without mutating or saving the original. A supplied group must contain exactly all eight valid colors; partial groups, nulls, unknown keys, and invalid colors are rejected by both frontend and backend. Save, copy, and export include the resolved group through the existing API and version-1 envelope. No database migration or separate syntax preferences are needed. Older application releases may reject these newer exports.\n\n## Selection And Defaults\n\n`SambeeThemeProvider` combines built-ins with the current user's themes and shared site themes from `GET /api/themes`. The per-user selection is saved separately through `appearance.theme_id` in `PUT /api/auth/me/settings`. The backend reports whether that value is an explicit override.\n\nA user without an override follows the site default (initially `sambee-light`). A user who explicitly chooses `sambee-light` keeps that ID even if an administrator changes the site default. The selected ID points at a theme definition, never at a frozen copy of a built-in. The provider refreshes shared themes, the default, and user settings on initial load, tab focus, visibility return, and local writes. It discards out-of-date responses when the account changes.\n\nAppearance settings display Your themes, Site themes, then Built-in themes. Clicking a tile or selecting its radio applies the theme and creates an explicit user override, even when it already matches the site default. Moving focus between radios doesn't change the applied theme or the target of Copy, Edit, Delete, and Set as default. The Default chip is distinct from the selected radio. Copy keeps writable themes in their group and copies read-only themes into Your themes without applying the copy. Editing read-only themes permits inspection and Save copy, but not Save. Only an administrator can save or delete site themes or make a built-in or site theme the default.\n\n## Companion Theme Delivery\n\nCompanion follows the active user's resolved theme on the authoritative paired server through [Shared Settings Delivery](../../companion-architecture/browser-to-companion-trust-model/#shared-settings-delivery). The backend resolves built-in and stored themes and the site default. It hashes the small Companion payload independently of directory policy. Persisted theme changes trigger synchronization; unchanged digests are no-ops. Native `ThemeState` broadcasts to existing windows and supplies the current theme to new windows. Routine paired delivery must not use a theme in a deep-link URI; that path is only a bootstrap fallback and cannot replace managed settings.\n\n## Editing And Persistence\n\nThe editor uses a responsive dialog with collapsible color groups. A swatch opens an alpha-aware picker and each color has an editable hex field. Invalid text stays in the field without changing the valid draft. Changes in the editor aren't applied to the app until Save succeeds; Cancel discards the draft. Import replaces only the draft after validating a versioned JSON definition, and Export writes the same format.\n\n`POST /api/themes` creates a theme. Save copy opens a destination menu with Your themes for everyone and Site themes for administrators. It always creates a new theme in the chosen group without changing the applied selection. If its name already exists in that group, the editor adds ` (copy)` or a numbered copy suffix. Save updates only the opened theme in its existing group and cannot create a copy. `PUT /api/themes/{id}` and `DELETE /api/themes/{id}?version=...` require the version read by the client; a stale version returns HTTP 409. The server checks ownership, admin permissions, names, IDs, and palette completeness before committing. Bulk writes to `appearance.custom_themes` are no longer supported. Legacy syntax compatibility is limited to an entirely absent syntax group; it doesn't repair incomplete older definitions.\n\nDeleting a theme clears explicit selections referencing it. If it was the site default, that setting is cleared too; users without an override then fall back to Sambee light. An explicit selection of another theme is unaffected.\n\n## Component Guidance\n\nPrefer the effective colors in `resolveThemePalette` and the MUI palette to hard-coded surfaces. `background.default` is the normal application surface; `background.paper` resolves to the same value for MUI compatibility. Dark chrome and dialogs use the editable `background.chrome` role. Markdown code, tables, blockquotes, and heading borders use the built-in theme's explicit document colors.\n\nViewer toolbar foreground variants, scrollbars, and subdued states can still derive opacity-adjusted values from their source color. Keep fixed colors for assets and file-type icons separate from the editor palette.\n\n## Shared Syntax Highlighting\n\nText viewing/editing, Markdown source and rendered Markdown fences share the CodeMirror language registry and tag mapping in `codeMirrorHighlightingCore.ts`. `syntaxHighlighting.ts` defines application-owned language IDs, UTF-16 token ranges, categories and explicit results that indicate plain text. Native editors and the syntax worker reuse that implementation. Fence aliases resolve to existing lazy grammars, including `mssql` to MS SQL and `mariadb` to MariaDB SQL. A `.sql` filename continues to select standard SQL; unknown fence labels aren't guessed.\n\nThe live Markdown viewer collects exact code occurrences from ReactMarkdown's existing AST, without another collection parse or embedded editors. A dedicated cancellable worker prepares syntax sequentially with acknowledged source chunks of at most 16,384 UTF-16 units and result pages of at most 512 ranges. Blocks above 100,000 UTF-16 units stay plain text. Nested Markdown fences use the configured Markdown parser, up to four Markdown levels including the outer block. Unknown, unlabelled and explicit plain-text fences remain neutral. A nested grammar load failure, or a parser error during static fence startup or advancement, leaves only the failed fence plain while retaining enclosing Markdown structure and successful siblings. The static adapter doesn't mutate cached grammars or retry parsing; later fences and preparations can still succeed. Closing during a pending grammar load terminates the generation's worker; reopening starts a fresh preparation. Cancellation still propagates, and exceeding the nesting limit intentionally keeps the whole outer block plain without suppressing unrelated blocks. There's no aggregate document-length or block-count cutoff. The pre-app browser capability gate requires the Web Worker API; Worker-less app operation isn't supported. The helper's defensive main-thread fallback isn't a supported browser mode or a responsiveness guarantee.\n\nEach preview generation owns cancellation and stale-result guards. After all requested blocks finish, the viewer paints at most 4,000 viewport syntax ranges through CSS Highlights. Vertical and horizontal clipping avoid publishing off-screen token ranges; scrolling, viewport resize, image loads and font readiness refresh presentation. Publication doesn't replace text nodes or insert token spans, preserving native text, whitespace, selection and the cached preview-search index. Missing highlight/visibility capabilities leave syntax plain instead of falling back to token DOM mutation. Disposal removes owned highlights, style, observers, listeners and queued frames. First visible syntax, complete preparation, memory and native interaction acceptance remain separate rollout gates; see [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/).\n\nThe existing theme provider installs stable application token rules once. Viewer/editor surfaces publish locally inherited CSS variables from the resolved MUI syntax palette, so changing theme colors doesn't require reparsing code or replacing token DOM. Identifiers and neutral code inherit the existing code foreground. Markdown source headings and structural markers use `keyword`; links use the existing link role; inline code uses the existing code foreground. Emphasis, strong text, and strikethrough change only their corresponding semantic treatment, not source font sizes or line geometry. Embedded code uses code categories, not Markdown prose styling.\n\nThe shared mapping also preserves built-ins, properties and keys, booleans, null, regular expressions, escapes, and metadata/directives when the grammar supplies those tags. `TOKEN_COLOR_ROLES` maps these categories to the existing eight syntax colors: built-ins use `function`; properties and regular expressions use `type`; booleans, null, and metadata use `keyword`; escapes use `operator`. Editors and rendered fences share this mapping without another parse or a theme schema change. Built-in names aren't necessarily commands, and grammar classifications vary: PowerShell variables and bare words can both remain neutral identifiers. There are no language-specific classification overrides.\n\nSearch matches use the viewer text foreground instead of syntax colors so matched keywords remain readable against their highlight backgrounds. Source editors apply that foreground to the match and its nested tokens. Preview search inherits `--sambee-search-foreground` from its own viewer; syntax highlights have priority -1, ordinary search highlights 0, and the current match 1. The shared search-color helper preserves the configured hues and uses 30%/36% opacity for ordinary/current matches in light mode and 40%/44% in dark mode. Custom theme validation checks color format and completeness, not contrast; choose text, syntax and surface colors that remain readable after alpha blending.\n\nTheme updates and lazy grammar completion preserve native selection, the active search match and both scroll axes on all four surfaces. Theme changes don't restart syntax preparation or renormalize unchanged Markdown. Late grammar completion can update editor token spans, while preview publication retains its original text nodes. These state guarantees don't establish scrolling performance, native clipboard behavior or close/navigation acceptance.\n\nReplacing an editor doesn't require replacing static highlighting. Replacing the engine requires preserving the application's requirements for token ranges and highlighting results, aliases where supported, and viewer lifecycle. Classification parity with a different engine isn't automatic. Removing CodeMirror entirely also requires migrating native editor integrations such as commands, autocomplete, and tables.\n\n## Verification\n\nRun focused theme tests and the project checks after changing the palette, API, or editor:\n\n```bash\ncd frontend \u0026\u0026 npm run test -- src/theme/__tests__ src/pages/__tests__/PreferencesSettings.test.tsx\ncd frontend \u0026\u0026 npm run build \u0026\u0026 npm run lint\ncd backend \u0026\u0026 .venv/bin/python -m pytest tests/test_user_settings.py\n```\n\nCheck the Appearance grid and editor on a phone and desktop in both built-in modes. Verify selection and saved-theme refresh after focus, color picker keyboard use and placement, alpha values and export, Cancel without applying the draft, and stale-save feedback.\n\nFor the production theme-dialog browser regressions, build the frontend first and keep the existing frontend/backend dev servers running. From `frontend/`, run:\n\n```bash\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production syntax theme dialog' --workers=1\n```\n\nThe suite serves built assets and intercepts theme APIs at `http://localhost:3000/browse/smb/demo`; it doesn't change stored themes. Chromium and Firefox cover save/cancel/copy, validation focus, personal/site/built-in permissions, alpha values, unchanged selection after copying, and rejected-save feedback at 1543x900 and 390x600. Narrow desktop viewports don't replace testing on a physical phone or with assistive technology.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/file-browser-and-navigation-model", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "file-browser-and-navigation-model", "title": "File Browser And Navigation Model", "path": "developer-guide/frontend-architecture/file-browser-and-navigation-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 133, "diff_removed": 20}}, "content_versions": {"0.7": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.8": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.9": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "1.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "2.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/routing.ts` | parses and serializes typed directory, viewer, editor, and settings locations |\n| `pages/FileBrowser/useWorkspaceNavigation.ts` | resolves viewer targets and owns workspace navigation and safe overlay return entries |\n| `hooks/useRoutedViewerEditing.tsx` | connects the active editor's existing confirmation dialog to React Router navigation blocking |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## Real-Time Directory Refresh\n\n### Directory Navigation Failures\n\nPhysical directory navigation has a pending target and a displayed location. Load the target through the content provider before committing its connection, path, rows, and route. A failed navigation keeps the previous displayed location, selection, and scroll state. Request cancellation and location guards reject late responses, including responses from automatic parent recovery.\n\nOnly successfully loaded physical directories become file-list subscription targets. Missing initial locations and deleted current directories recover to an accessible parent, or clear stale rows and keep recovery controls visible. Canonical recovery replaces the affected route; it does not use browser Back or change the other pane.\n\nThe SMB storage boundary translates named missing-name, missing-parent, access-denied, and wrong-type statuses into typed storage errors. Directory listing returns a structured API code and a safe message. Only a confirmed `directory_not_found` result permits stale history and directory-index removal. A connection-level HTTP 404 is not proof that a folder was deleted.\n\nCompanion directory listings use the same `directory_not_found`, `directory_access_denied`, `not_a_directory`, and `directory_unavailable` codes. Companion responses put `code` beside the safe `detail` string; SMB responses put the code inside `detail`. The pane accepts both formats. Local path validation and directory reads use the directory error mapper, while unavailable drive roots remain separate from missing folders. Do not remove folder history for an unavailable drive. The existing drive-boundary and path-traversal checks still apply.\n\n`components/OperationNotifications.tsx` provides one viewport-centered notification host for both panes, viewers, and page operations. `OperationNotificationProvider` collects active notices from their existing owners. It does not own navigation, history, editor text, or locks. The host moves inside the top open dialog for modal focus access. It does not change file-row geometry.\n\nErrors precede warnings and information. Equal-priority sources retain registration order. Only one toast is visible; Next notification exposes other active failures without dismissing the current failure. There is no historical event queue. Pending notices come only from mounted owners' current state, and resolved or unmounted sources retire their notices. Optional failure keys deduplicate one failure across owners without merging different targets.\n\nToasts have a finite duration by default. `NOTICE_DURATION_MS` defines 6 seconds for information and completed results, 10 seconds for browser failures and service status, and 15 seconds for editor errors and safety warnings. Folder-recovery results use 6 seconds even though their severity is warning. Retry and Settings actions do not make a toast persistent.\n\nSet `persistent: true` only for an active upload or download with Cancel, share preparation with Cancel, or a ready-to-share decision with Share and Cancel. Sharing after confirmation uses the 6-second information timeout. These exceptions use the existing toast controls; they do not add another progress or status surface. Unsaved-change, conflict, password, and draft-recovery dialogs keep their existing decision behavior.\n\nA timer starts when its toast becomes visible, pauses during hover or keyboard focus, and does not restart for routine message updates. Expiry hides the toast without calling its `onDismiss` callback or its source's dismissal callback. Only completed informational results use `onExpire` to clear their display flags, so a later identical result can appear again. Expiry must not clear unresolved errors, cancel operations, discard drafts, or mark pairing or monitoring as healthy. Occurrence identities allow a new attempt to show the same error after expiry or dismissal. Retry retains its original target rather than following the active pane or selected row.\n\nTarget-specific notices show the message first, followed by smaller, regular-weight context on a separate line. `formatNoticeTarget` captures the connection name and full connection-relative path, including the failed file or folder. The root is `/`. Render this context with `DialogIdentifierDisplay` in its text appearance. It uses the shared grapheme-aware `abbreviatePath` algorithm to fit the visual path on one line, preserving the connection prefix and useful trailing segments where space permits. It recalculates when the available width changes. The complete value remains in the accessible name and a hover-only tooltip; shortening must not change failure identity or the Retry target. Bidirectional text is isolated. These paths do not expose the server's physical filesystem root. Global notices without a target have no context line. Known missing-file and missing-folder errors use short toast summaries without repeating the target name; inline errors and dialogs keep their detailed messages. Other error text is not rewritten.\n\nEach failure captures its own target rather than following the active pane or selected row. A recovery result identifies the original missing path, even after an accessible parent loads. If a parent fails during recovery, its failure notice identifies that parent instead. Refresh always reloads the displayed folder; it does not replay a failed navigation or native launch. Native Retry uses the item resolved by the original attempt. Backend and Companion status recovery remains available from the existing header warning menu after notification expiry or dismissal, without covering bottom file actions. The existing monitoring control and initial-folder error state also remain available. No additional inline editor warning or progress control is added when a toast expires.\n\nAn unavailable initial directory uses an unframed error state in the list area, with the original location and recovery actions. A usable previous listing, including an empty folder, remains visible after a failed target request. Loading and onboarding have their own content states. Stopped automatic updates retain a compact recovery control after toast dismissal. Backend outages have one transition notice and a persistent status control; a brief reconnection does not start another notice cycle. Expected monitor startup failures do not produce duplicate tracebacks.\n\nAutomatic parent recovery skips missing, inaccessible, and wrong-type parents within the configured root. It stops on cancellation, a newer request, pairing failure, timeout, or unavailable storage. A directory-only route replacement retains the active viewer identity and selection revision. It must not reload content, unmount a dirty editor, or acquire another edit lock.\n\n### Subscription Acknowledgements\n\nBoth WebSocket transports attach a request ID to each directory subscription. Requested and acknowledged subscriptions are separate. A reply is accepted only for the current socket, request ID, and requested location. Unsubscribe and socket cleanup retire that state and its bounded acknowledgement timer.\n\nDirectory-change events are accepted only from the socket that acknowledged the current subscription. Events before acknowledgement, after failure, or after retirement cannot refresh the pane. A successful directory refresh alone does not clear a monitor failure; the matching acknowledgement clears it.\n\nSubscription errors include the connection, path, request ID, and a safe code. Confirmed absence invalidates that exact location through the pane refresh scheduler; the fresh listing decides whether parent recovery is needed. Other subscription failures retain valid rows and show persistent Retry controls. They do not prove deletion or start an automatic subscribe/reload loop. A running monitor invalidates its deleted directory before retiring its watcher state.\n\n### Refresh Scheduling\n\nEach pane handles directory-change notifications independently. An automatic refresh keeps an already loaded physical-directory listing mounted, including an empty listing, so unchanged rows retain selection, keyboard focus, and scroll position. Initial loading and navigation without a usable snapshot still show loading feedback.\n\nNotifications don't cancel an active listing request. Instead, the pane remembers that another refresh is needed and starts one follow-up request after the active request finishes. Automatic refreshes start at most once per second. Further notifications don't move an existing deadline, so continuous writes still produce periodic updates. Navigation and unmount cancel queued work.\n\nA listing with unprocessed change notifications can remain visible, but it isn't cached as fresh. Deferred link-target metadata only updates cache entries that are still valid, so cancelling a follow-up refresh can't make an outdated snapshot reusable on return.\n\nSMB file-list subscriptions watch immediate children rather than the whole subtree. The separate backend directory-search cache retains recursive directory-name monitoring. See [SMB Change Notification and Directory Freshness](../../backend-architecture/smb-change-notification-and-directory-freshness/) for watcher ownership and lifecycle.\n\n## Progressive Quick-Bar Results\n\nPublish usable history and loaded-file results without waiting for index requests. Publish selectable records before rendering rows, merge duplicate history/index results, and reject responses for obsolete queries or sources.\n\nTreat incomplete coverage separately from request failure. Background refresh requires `search_contract_version: 1` and must stop when the query, source, visibility, or search session changes, or on terminal failure. See [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for storage and freshness rules.\n\nStatus messages include the connection name. A status becomes a mouse/touch-only link only when it has additional information; do not add an icon or a keyboard tab stop. `SearchStatusDialog` uses `ResponsiveDialogShell`, retains the query and selected result, and returns focus to the quick bar when closed. Source changes close the dialog and cancel its details request. Directory details load on demand through `include_issue_details`; specific request errors use the already received message. Messages without extra information remain plain text.\n\n## URL-Driven Workspace Navigation\n\nThe URL selects the directory, pane layout, viewer, editing intent, and settings view. The file browser stays mounted under overlays. Loaded content, drafts, locks, selection, scroll, search panels, and zoom remain runtime state.\n\n| Part | Meaning |\n|---|---|\n| `/browse/smb/\u003cslug\u003e/\u003cpath\u003e` | Primary SMB pane |\n| `/browse/local/\u003cdrive-id\u003e/\u003cpath\u003e` | Primary companion-drive pane |\n| `p2=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Right pane, enabled when present |\n| `active=2` | Right pane is active |\n| `file=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Viewer target, independent of the directory and active pane |\n| `viewer=image\\|markdown\\|pdf\\|text` | Requested browser viewer |\n| `mode=edit` | Editing intent for text or Markdown |\n| `pane=2` | Right pane owns the viewer; requires a right-pane target |\n| `virtual=\u003cJSON array\u003e` | Archive member descriptor: provider ID, source archive path, member path |\n| `settings=main\\|\u003ccategory\u003e` | Settings main view or category from the shared category registry |\n\nFor example:\n\n```text\n/browse/smb/my-server/documents\n/browse/smb/my-server/documents?p2=smb%2Fother-server%2Fphotos\u0026active=2\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\u0026mode=edit\n/browse/smb/my-server/documents?settings=account\n```\n\nUse the shared parser/serializer and `URLSearchParams`, not concatenated query strings. File descriptors encode target IDs and individual path segments before query serialization. The archive provider is currently `zip`. Runtime session IDs, file contents, MIME guesses, gallery arrays, credentials, and lock capabilities never belong in navigation state.\n\n### Navigation and Dismissal\n\nOpening or closing a viewer, entering or leaving editing, changing gallery images, opening or closing settings, and changing settings categories push history entries. Repeating the same location does nothing. Pane-focus updates, invalid-descriptor recovery, failed edit acquisition, and canonicalization replace the current entry. Unrelated query parameters and authentication fragments are preserved.\n\nBack and Forward follow actual history without adding entries. Explicit Close pushes the current workspace with the dismissed layer removed, including for direct links and refreshed viewers. For example, opening a directory, opening an image, and closing it produces directory, image, and directory entries; Back reopens the image before returning to the earlier directory entry. A new action after Back discards the old Forward branch, following normal browser behavior. Close doesn't depend on opening-entry metadata or `history.length`. Settings back controls traverse observed history; without an observed predecessor they replace the URL with an in-app parent.\n\nDesktop settings and the mobile drawer are controlled by the same category descriptor. `settings=main` displays the desktop default category or the mobile category list. Resizing changes presentation without navigation. Standalone `/settings/...` routes and their aliases use the same category content and authorization checks. User Management owns its query keys through React Router, merging them with workspace parameters.\n\n### Direct Links and Recovery\n\nViewer links resolve metadata through the storage registry or content provider, without simulated file-row clicks. Resolution is cancelled when its identity changes. Missing resources show Retry and Close actions. A viewer URL never falls back to opening a native application.\n\nThe incoming URL always wins over a browser recovery snapshot. Snapshot hydration matches each pane's resource identity, clears legacy viewer state, and ignores unmatched panes. A bare `/browse` uses normal default navigation. Captured snapshots use the current canonical workspace URL and contain neither callback fragments nor edit-session tokens.\n\n### Physical File Failures\n\n`utils/apiErrors.ts` classifies nested SMB codes and top-level Companion codes. `item_not_found` means confirmed physical absence. Metadata also serves directories; `not_a_file` is reserved for operations that require a regular file. Missing connections, unavailable drive roots, archive members, pairing failures, and expired tokens remain separate. An HTTP 404 alone is not evidence that a physical file was deleted.\n\nPhysical viewer reads decode a structured binary error only when its content type is JSON and its size is bounded. An ambiguous image or PDF decode failure can make one guarded metadata request for the current resource. Existing metadata does not turn a decode failure into a deletion. Abort signals, viewer identities, and source URLs reject stale results.\n\n`services/fileRecoveryEvents.ts` carries confirmed absence to the existing pane refresh owner. Each pane invalidates the physical parent cache; only a pane still displaying that connection and parent schedules a refresh. This event does not own notices, history deletion, or editor recovery. Activation errors use pane notices. Viewer errors use the existing viewer controls, without an additional toast.\n\nRecent-file validation removes only the identified record for confirmed absence, a non-file target, an invalid stored target, or an authoritatively deleted stored connection. Item-level and connection-level access denial, generic launch failure, timeout, cancellation, pairing failure, unavailable storage, and unknown errors retain history. Publish the cross-tab change event only after actual cleanup. Recent-directory cleanup still requires an explicit missing-directory result.\n\nBrowser editor writes use ordinary create-or-overwrite behavior with the active editor lease. Save can recreate a deleted file at its original path. New lock acquisition still requires an existing regular file and must not create or truncate it. SMB requires existing parent directories; Companion uploads retain their normal parent-directory creation behavior within the available drive. A normal write can overwrite changes made at the same path; it does not compare the file with the editor baseline before writing. A failed save keeps the draft and dirty state. After a successful upload, a failed metadata refresh leaves the upload successful with an unknown modified timestamp. It must not cause an automatic repeat of the write. Native URI dispatch is not a launch acknowledgement. Do not infer later application success or failure from that handoff.\n\n### Viewer Loading and Transitions\n\nLoading feedback belongs to the selected image, PDF, text, or Markdown viewer. Workspace metadata resolution and dynamic component imports do not show an intermediate full-screen loading dialog. On an initial opening, the browser remains visible until metadata and the viewer component are available; the viewer then displays its existing content-loading feedback.\n\nOne viewer component is mounted at a time. Metadata resolution and component imports can retain the displayed resource while controls and shortcuts are suspended; Escape remains available. Once the selected component and metadata are available, that viewer owns content loading and errors. There is no hidden candidate viewer or content-readiness promotion. The editor leave guard remains the sole owner of dirty-navigation decisions.\n\nImage-gallery navigation updates the current index in the same viewer instance and publishes it to the route. The gallery keeps its local bounded cache and preloading; no image-byte cache is shared between viewer instances. An image is ready only when its decoded source exists. A failed image uses the selected image's error controls without displaying the previous image under a new filename. Explicit Retry invalidates failed local bytes and makes a fresh request. Encrypted PDFs retain the standard responsive password dialog.\n\nViewer content failures use the selected viewer's error state with Retry and Close, not a generic replacement toast. Individual loaders reject late results after a newer selection or close. There is no guarantee that a previous document remains displayed until the next document's content is ready.\n\nOne dynamic viewer host serves both panes. An explicit viewer ID, not an image's changing MIME type, controls component loading. Text and Markdown still reset resource-local state when the actual file changes; mode-only and settings-only navigation do not restart the viewer.\n\n### Editing and Router Integrity\n\nThe app uses a data router (`createBrowserRouter` and `RouterProvider`) for supported `useBlocker` behavior. One guard owner delegates resource-leaving transitions to the active text or Markdown editor when its draft is dirty, a save is pending, or a session is being acquired. Clean editor Back and Forward navigate directly, avoiding the history reversal required by a blocked browser navigation. Cancel keeps the draft and lock; successful Save or Discard continues the original transition; failed Save keeps the editor open. Changes that retain the same edited resource and mode don't discard its draft. Dirty drafts also register `beforeunload` protection.\n\nEdit bookmarks and history navigation back into editing acquire a fresh edit session after content and permission checks. Navigating away during acquisition invalidates the attempt and releases any late lock. Leaving editing releases its session once. The outgoing editor is read-only during cleanup, and re-entry waits for that cleanup to finish so an old release can't clear a new session. History restores navigation intent, not old file contents, discarded drafts, or saved locks. An edit URL doesn't grant permission.\n\nFull page reloads, including F5 and the update prompt, can resume the same edit lock. The shared storage edit-session layer keeps lock credentials separately in tab-scoped session storage, keyed by user, connection, and file. On reload it validates those credentials with a heartbeat before reusing them. Only a structured lost-lock response permits fresh acquisition; network and permission failures don't trigger replacement. Credentials follow replacement locks and are removed on successful release or logout. Unsaved text still uses the existing draft-recovery flow.\n\nRecovery requires session storage and the browser Web Locks API, available in secure contexts such as HTTPS and localhost. An exclusive Web Lock prevents another tab from using copied recovery credentials, even if that tab reloads. Without those capabilities, editing still works, but a reload may need to wait for the abandoned server lock to expire. Fresh navigations and history entries don't resume saved credentials, and no credentials appear in the URL or workspace recovery snapshot.\n\nUse router navigation for all mounted-route URL writes, including authentication fragment cleanup. `useRemoveLocationFragment` replaces the entry, removes only consumed fragment keys, and preserves the full query and application state. Never clear router-managed history state with `replaceState(null, ...)`: doing so can disable POP blocking.\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.8": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.9": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "1.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "2.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/routing.ts` | parses and serializes typed directory, viewer, editor, and settings locations |\n| `pages/FileBrowser/useWorkspaceNavigation.ts` | resolves viewer targets and owns workspace navigation and safe overlay return entries |\n| `hooks/useRoutedViewerEditing.tsx` | connects the active editor's existing confirmation dialog to React Router navigation blocking |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## Real-Time Directory Refresh\n\n### Directory Navigation Failures\n\nPhysical directory navigation has a pending target and a displayed location. Load the target through the content provider before committing its connection, path, rows, and route. A failed navigation keeps the previous displayed location, selection, and scroll state. Request cancellation and location guards reject late responses, including responses from automatic parent recovery.\n\nOnly successfully loaded physical directories become file-list subscription targets. Missing initial locations and deleted current directories recover to an accessible parent, or clear stale rows and keep recovery controls visible. Canonical recovery replaces the affected route; it does not use browser Back or change the other pane.\n\nThe SMB storage boundary translates named missing-name, missing-parent, access-denied, and wrong-type statuses into typed storage errors. Directory listing returns a structured API code and a safe message. Only a confirmed `directory_not_found` result permits stale history and directory-index removal. A connection-level HTTP 404 is not proof that a folder was deleted.\n\nCompanion directory listings use the same `directory_not_found`, `directory_access_denied`, `not_a_directory`, and `directory_unavailable` codes. Companion responses put `code` beside the safe `detail` string; SMB responses put the code inside `detail`. The pane accepts both formats. Local path validation and directory reads use the directory error mapper, while unavailable drive roots remain separate from missing folders. Do not remove folder history for an unavailable drive. The existing drive-boundary and path-traversal checks still apply.\n\n`components/OperationNotifications.tsx` provides one viewport-centered notification host for both panes, viewers, and page operations. `OperationNotificationProvider` collects active notices from their existing owners. It does not own navigation, history, editor text, or locks. The host moves inside the top open dialog for modal focus access. It does not change file-row geometry.\n\nErrors precede warnings and information. Equal-priority sources retain registration order. Only one toast is visible; Next notification exposes other active failures without dismissing the current failure. There is no historical event queue. Pending notices come only from mounted owners' current state, and resolved or unmounted sources retire their notices. Optional failure keys deduplicate one failure across owners without merging different targets.\n\nToasts have a finite duration by default. `NOTICE_DURATION_MS` defines 6 seconds for information and completed results, 10 seconds for browser failures and service status, and 15 seconds for editor errors and safety warnings. Folder-recovery results use 6 seconds even though their severity is warning. Retry and Settings actions do not make a toast persistent.\n\nSet `persistent: true` only for an active upload or download with Cancel, share preparation with Cancel, or a ready-to-share decision with Share and Cancel. Sharing after confirmation uses the 6-second information timeout. These exceptions use the existing toast controls; they do not add another progress or status surface. Unsaved-change, conflict, password, and draft-recovery dialogs keep their existing decision behavior.\n\nA timer starts when its toast becomes visible, pauses during hover or keyboard focus, and does not restart for routine message updates. Expiry hides the toast without calling its `onDismiss` callback or its source's dismissal callback. Only completed informational results use `onExpire` to clear their display flags, so a later identical result can appear again. Expiry must not clear unresolved errors, cancel operations, discard drafts, or mark pairing or monitoring as healthy. Occurrence identities allow a new attempt to show the same error after expiry or dismissal. Retry retains its original target rather than following the active pane or selected row.\n\nTarget-specific notices show the message first, followed by smaller, regular-weight context on a separate line. `formatNoticeTarget` captures the connection name and full connection-relative path, including the failed file or folder. The root is `/`. Render this context with `DialogIdentifierDisplay` in its text appearance. It uses the shared grapheme-aware `abbreviatePath` algorithm to fit the visual path on one line, preserving the connection prefix and useful trailing segments where space permits. It recalculates when the available width changes. The complete value remains in the accessible name and a hover-only tooltip; shortening must not change failure identity or the Retry target. Bidirectional text is isolated. These paths do not expose the server's physical filesystem root. Global notices without a target have no context line. Known missing-file and missing-folder errors use short toast summaries without repeating the target name; inline errors and dialogs keep their detailed messages. Other error text is not rewritten.\n\nEach failure captures its own target rather than following the active pane or selected row. A recovery result identifies the original missing path, even after an accessible parent loads. If a parent fails during recovery, its failure notice identifies that parent instead. Refresh always reloads the displayed folder; it does not replay a failed navigation or native launch. Native Retry uses the item resolved by the original attempt. Backend and Companion status recovery remains available from the existing header warning menu after notification expiry or dismissal, without covering bottom file actions. The existing monitoring control and initial-folder error state also remain available. No additional inline editor warning or progress control is added when a toast expires.\n\nAn unavailable initial directory uses an unframed error state in the list area, with the original location and recovery actions. A usable previous listing, including an empty folder, remains visible after a failed target request. Loading and onboarding have their own content states. Stopped automatic updates retain a compact recovery control after toast dismissal. Backend outages have one transition notice and a persistent status control; a brief reconnection does not start another notice cycle. Expected monitor startup failures do not produce duplicate tracebacks.\n\nAutomatic parent recovery skips missing, inaccessible, and wrong-type parents within the configured root. It stops on cancellation, a newer request, pairing failure, timeout, or unavailable storage. A directory-only route replacement retains the active viewer identity and selection revision. It must not reload content, unmount a dirty editor, or acquire another edit lock.\n\n### Subscription Acknowledgements\n\nBoth WebSocket transports attach a request ID to each directory subscription. Requested and acknowledged subscriptions are separate. A reply is accepted only for the current socket, request ID, and requested location. Unsubscribe and socket cleanup retire that state and its bounded acknowledgement timer.\n\nDirectory-change events are accepted only from the socket that acknowledged the current subscription. Events before acknowledgement, after failure, or after retirement cannot refresh the pane. A successful directory refresh alone does not clear a monitor failure; the matching acknowledgement clears it.\n\nSubscription errors include the connection, path, request ID, and a safe code. Confirmed absence invalidates that exact location through the pane refresh scheduler; the fresh listing decides whether parent recovery is needed. Other subscription failures retain valid rows and show persistent Retry controls. They do not prove deletion or start an automatic subscribe/reload loop. A running monitor invalidates its deleted directory before retiring its watcher state.\n\n### Refresh Scheduling\n\nEach pane handles directory-change notifications independently. An automatic refresh keeps an already loaded physical-directory listing mounted, including an empty listing, so unchanged rows retain selection, keyboard focus, and scroll position. Initial loading and navigation without a usable snapshot still show loading feedback.\n\nNotifications don't cancel an active listing request. Instead, the pane remembers that another refresh is needed and starts one follow-up request after the active request finishes. Automatic refreshes start at most once per second. Further notifications don't move an existing deadline, so continuous writes still produce periodic updates. Navigation and unmount cancel queued work.\n\nA listing with unprocessed change notifications can remain visible, but it isn't cached as fresh. Deferred link-target metadata only updates cache entries that are still valid, so cancelling a follow-up refresh can't make an outdated snapshot reusable on return.\n\nSMB file-list subscriptions watch immediate children rather than the whole subtree. The separate backend directory-search cache retains recursive directory-name monitoring. See [SMB Change Notification and Directory Freshness](../../backend-architecture/smb-change-notification-and-directory-freshness/) for watcher ownership and lifecycle.\n\n## Progressive Quick-Bar Results\n\nPublish usable history and loaded-file results without waiting for index requests. Publish selectable records before rendering rows, merge duplicate history/index results, and reject responses for obsolete queries or sources.\n\nTreat incomplete coverage separately from request failure. Background refresh requires `search_contract_version: 1` and must stop when the query, source, visibility, or search session changes, or on terminal failure. See [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for storage and freshness rules.\n\nStatus messages include the connection name. A status becomes a mouse/touch-only link only when it has additional information; do not add an icon or a keyboard tab stop. `SearchStatusDialog` uses `ResponsiveDialogShell`, retains the query and selected result, and returns focus to the quick bar when closed. Source changes close the dialog and cancel its details request. Directory details load on demand through `include_issue_details`; specific request errors use the already received message. Messages without extra information remain plain text.\n\n## URL-Driven Workspace Navigation\n\nThe URL selects the directory, pane layout, viewer, editing intent, and settings view. The file browser stays mounted under overlays. Loaded content, drafts, locks, selection, scroll, search panels, and zoom remain runtime state.\n\n| Part | Meaning |\n|---|---|\n| `/browse/smb/\u003cslug\u003e/\u003cpath\u003e` | Primary SMB pane |\n| `/browse/local/\u003cdrive-id\u003e/\u003cpath\u003e` | Primary companion-drive pane |\n| `p2=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Right pane, enabled when present |\n| `active=2` | Right pane is active |\n| `file=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Viewer target, independent of the directory and active pane |\n| `viewer=image\\|markdown\\|pdf\\|text` | Requested browser viewer |\n| `mode=edit` | Editing intent for text or Markdown |\n| `pane=2` | Right pane owns the viewer; requires a right-pane target |\n| `virtual=\u003cJSON array\u003e` | Archive member descriptor: provider ID, source archive path, member path |\n| `settings=main\\|\u003ccategory\u003e` | Settings main view or category from the shared category registry |\n\nFor example:\n\n```text\n/browse/smb/my-server/documents\n/browse/smb/my-server/documents?p2=smb%2Fother-server%2Fphotos\u0026active=2\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\u0026mode=edit\n/browse/smb/my-server/documents?settings=account\n```\n\nUse the shared parser/serializer and `URLSearchParams`, not concatenated query strings. File descriptors encode target IDs and individual path segments before query serialization. The archive provider is currently `zip`. Runtime session IDs, file contents, MIME guesses, gallery arrays, credentials, and lock capabilities never belong in navigation state.\n\n### Navigation and Dismissal\n\nOpening or closing a viewer, entering or leaving editing, changing gallery images, opening or closing settings, and changing settings categories push history entries. Repeating the same location does nothing. Pane-focus updates, invalid-descriptor recovery, failed edit acquisition, and canonicalization replace the current entry. Unrelated query parameters and authentication fragments are preserved.\n\nBack and Forward follow actual history without adding entries. Explicit Close pushes the current workspace with the dismissed layer removed, including for direct links and refreshed viewers. For example, opening a directory, opening an image, and closing it produces directory, image, and directory entries; Back reopens the image before returning to the earlier directory entry. A new action after Back discards the old Forward branch, following normal browser behavior. Close doesn't depend on opening-entry metadata or `history.length`. Settings back controls traverse observed history; without an observed predecessor they replace the URL with an in-app parent.\n\nDesktop settings and the mobile drawer are controlled by the same category descriptor. `settings=main` displays the desktop default category or the mobile category list. Resizing changes presentation without navigation. Standalone `/settings/...` routes and their aliases use the same category content and authorization checks. User Management owns its query keys through React Router, merging them with workspace parameters.\n\n### Direct Links and Recovery\n\nViewer links resolve metadata through the storage registry or content provider, without simulated file-row clicks. Resolution is cancelled when its identity changes. Missing resources show Retry and Close actions. A viewer URL never falls back to opening a native application.\n\nThe incoming URL always wins over a browser recovery snapshot. Snapshot hydration matches each pane's resource identity, clears legacy viewer state, and ignores unmatched panes. A bare `/browse` uses normal default navigation. Captured snapshots use the current canonical workspace URL and contain neither callback fragments nor edit-session tokens.\n\n### Physical File Failures\n\n`utils/apiErrors.ts` classifies nested SMB codes and top-level Companion codes. `item_not_found` means confirmed physical absence. Metadata also serves directories; `not_a_file` is reserved for operations that require a regular file. Missing connections, unavailable drive roots, archive members, pairing failures, and expired tokens remain separate. An HTTP 404 alone is not evidence that a physical file was deleted.\n\nPhysical viewer reads decode a structured binary error only when its content type is JSON and its size is bounded. An ambiguous image or PDF decode failure can make one guarded metadata request for the current resource. Existing metadata does not turn a decode failure into a deletion. Abort signals, viewer identities, and source URLs reject stale results.\n\n`services/fileRecoveryEvents.ts` carries confirmed absence to the existing pane refresh owner. Each pane invalidates the physical parent cache; only a pane still displaying that connection and parent schedules a refresh. This event does not own notices, history deletion, or editor recovery. Activation errors use pane notices. Viewer errors use the existing viewer controls, without an additional toast.\n\nRecent-file validation removes only the identified record for confirmed absence, a non-file target, an invalid stored target, or an authoritatively deleted stored connection. Item-level and connection-level access denial, generic launch failure, timeout, cancellation, pairing failure, unavailable storage, and unknown errors retain history. Publish the cross-tab change event only after actual cleanup. Recent-directory cleanup still requires an explicit missing-directory result.\n\nBrowser editor writes use ordinary create-or-overwrite behavior with the active editor lease. Save can recreate a deleted file at its original path. New lock acquisition still requires an existing regular file and must not create or truncate it. SMB requires existing parent directories; Companion uploads retain their normal parent-directory creation behavior within the available drive. A normal write can overwrite changes made at the same path; it does not compare the file with the editor baseline before writing. A failed save keeps the draft and dirty state. After a successful upload, a failed metadata refresh leaves the upload successful with an unknown modified timestamp. It must not cause an automatic repeat of the write. Native URI dispatch is not a launch acknowledgement. Do not infer later application success or failure from that handoff.\n\n### Viewer Loading and Transitions\n\nLoading feedback belongs to the selected image, PDF, text, or Markdown viewer. Workspace metadata resolution and dynamic component imports do not show an intermediate full-screen loading dialog. On an initial opening, the browser remains visible until metadata and the viewer component are available; the viewer then displays its existing content-loading feedback.\n\nOne viewer component is mounted at a time. Metadata resolution and component imports can retain the displayed resource while controls and shortcuts are suspended; Escape remains available. Once the selected component and metadata are available, that viewer owns content loading and errors. There is no hidden candidate viewer or content-readiness promotion. The editor leave guard remains the sole owner of dirty-navigation decisions.\n\nImage-gallery navigation updates the current index in the same viewer instance and publishes it to the route. The gallery keeps its local bounded cache and preloading; no image-byte cache is shared between viewer instances. An image is ready only when its decoded source exists. A failed image uses the selected image's error controls without displaying the previous image under a new filename. Explicit Retry invalidates failed local bytes and makes a fresh request. Encrypted PDFs retain the standard responsive password dialog.\n\nViewer content failures use the selected viewer's error state with Retry and Close, not a generic replacement toast. Individual loaders reject late results after a newer selection or close. There is no guarantee that a previous document remains displayed until the next document's content is ready.\n\nOne dynamic viewer host serves both panes. An explicit viewer ID, not an image's changing MIME type, controls component loading. Text and Markdown still reset resource-local state when the actual file changes; mode-only and settings-only navigation do not restart the viewer.\n\n### Editing and Router Integrity\n\nThe app uses a data router (`createBrowserRouter` and `RouterProvider`) for supported `useBlocker` behavior. One guard owner delegates resource-leaving transitions to the active text or Markdown editor when its draft is dirty, a save is pending, or a session is being acquired. Clean editor Back and Forward navigate directly, avoiding the history reversal required by a blocked browser navigation. Cancel keeps the draft and lock; successful Save or Discard continues the original transition; failed Save keeps the editor open. Changes that retain the same edited resource and mode don't discard its draft. Dirty drafts also register `beforeunload` protection.\n\nEdit bookmarks and history navigation back into editing acquire a fresh edit session after content and permission checks. Navigating away during acquisition invalidates the attempt and releases any late lock. Leaving editing releases its session once. The outgoing editor is read-only during cleanup, and re-entry waits for that cleanup to finish so an old release can't clear a new session. History restores navigation intent, not old file contents, discarded drafts, or saved locks. An edit URL doesn't grant permission.\n\nFull page reloads, including F5 and the update prompt, can resume the same edit lock. The shared storage edit-session layer keeps lock credentials separately in tab-scoped session storage, keyed by user, connection, and file. On reload it validates those credentials with a heartbeat before reusing them. Only a structured lost-lock response permits fresh acquisition; network and permission failures don't trigger replacement. Credentials follow replacement locks and are removed on successful release or logout. Unsaved text still uses the existing draft-recovery flow.\n\nRecovery requires session storage and the browser Web Locks API, available in secure contexts such as HTTPS and localhost. An exclusive Web Lock prevents another tab from using copied recovery credentials, even if that tab reloads. Without those capabilities, editing still works, but a reload may need to wait for the abandoned server lock to expire. Fresh navigations and history entries don't resume saved credentials, and no credentials appear in the URL or workspace recovery snapshot.\n\nUse router navigation for all mounted-route URL writes, including authentication fragment cleanup. `useRemoveLocationFragment` replaces the entry, removes only consumed fragment keys, and preserves the full query and application state. Never clear router-managed history state with `replaceState(null, ...)`: doing so can disable POP blocking.\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/keyboard-shortcuts-and-command-model", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "keyboard-shortcuts-and-command-model", "title": "Keyboard Shortcuts And Command Model", "path": "developer-guide/frontend-architecture/keyboard-shortcuts-and-command-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 14, "diff_removed": 6}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 2, "diff_removed": 63}}, "content_versions": {"0.7": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.8": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.9": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "1.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "2.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\n`browser.focusLeftPane` and `browser.focusRightPane` remain available through command search without keyboard bindings. Do not register `Ctrl+1`, `Ctrl+2`, or their Meta equivalents for pane focus. These keys remain available to the browser. The right-pane command also opens dual-pane mode when only one pane is visible.\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system."}, "page_contents": {"0.7": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.8": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.9": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "1.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "2.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\n`browser.focusLeftPane` and `browser.focusRightPane` remain available through command search without keyboard bindings. Do not register `Ctrl+1`, `Ctrl+2`, or their Meta equivalents for pane focus. These keys remain available to the browser. The right-pane command also opens dual-pane mode when only one pane is visible.\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "viewer-architecture-and-preview-contracts", "title": "Viewer Architecture And Preview Contracts", "path": "developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 211, "diff_removed": 10}}, "content_versions": {"0.7": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.8": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.9": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "1.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "2.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must agree on image formats, conversion requirements, and MIME types used for dedicated viewers\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/fileLanguages.ts` | shared CodeMirror language catalogue, filename matching, and additional plain-text extensions used by highlighting and default text opening |\n| `frontend/src/utils/FileTypeRegistry.ts` | dedicated viewer mappings and MIME/presentation metadata; derives text-editor support from shared filename recognition |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nDedicated formats such as images require backend and frontend agreement. Text-file recognition instead uses `fileLanguages.ts`: both highlighting and default text opening consume the same CodeMirror catalogue. Language metadata doesn't load a grammar or import the highlighting core into the file browser.\n\nExplicit image, PDF, and Markdown viewers take precedence over extension-based text recognition. A recognized, non-generic MIME type with a viewer mapping takes precedence over the filename; empty MIME types, `application/octet-stream`, and `text/plain` fall back to filename recognition. Saved viewer preferences override the default selection. Unknown files still use the viewer picker unless a MIME mapping or saved preference selects a viewer.\n\nAll file viewers and editors use `useViewerDocumentTitle` to set the browser tab title to the active filename, including its extension. Image navigation updates the title to the active image. Native print events temporarily remove the final extension so browsers can suggest a clean PDF filename. The Markdown Print action uses the hook's print callback to prepare the title before opening the dialog and restore it after a print failure. Successful calls retain the short title until `afterprint`; `window.print()` can return before the print dialog closes. Closing the workspace restores the previous title unless another owner has changed it.\n\n## Unified Text Editor\n\n`TextEditor.tsx` owns the text destination and reuses `TextCodeEditor` for writable and read-only content. There isn't a separate text-viewer component or an Edit action. The public `viewer=text` identifier, viewer preferences, settings, and recovery-draft keys remain compatible. Text routes accept absent, `view`, and `edit` modes as the same destination; canonical URLs omit `mode` without adding a history entry or dropping fragments. Markdown still uses its existing preview/edit route modes.\n\nOpening an eligible text file automatically calls `beginViewerTextEdit`. The editor stays read-only until acquisition succeeds and a fresh content read establishes the baseline. Archive members, read-only connections, and oversized files don't acquire sessions. Storage boundaries distinguish contention, denied permissions, unsupported editing, and temporary unavailability. SMB's acquisition request opts into a non-mutating per-file write probe; Companion also checks an existing file with read/write open and no creation or truncation.\n\nAcquisition feedback appears after 200 ms as a small spinner beside the filename, in a fixed-size toolbar slot. Fast acquisitions show no progress message, and slower ones don't move the document. Completion, navigation, and unmount cancel pending feedback without delaying readiness. Access failures remain immediate; related error details and the read-only reason share one notice with Retry where supported.\n\nAcquisition uses an activation generation to release obsolete results, and a pending release completes before another acquisition starts. Confirmed lock loss or revoked access freezes mutations and retains the draft; a transient heartbeat failure shows a warning. Retry is explicit, not an acquisition loop. A fresh baseline that differs from a retained draft's original baseline requires a conflict decision before editing resumes. Choosing the draft doesn't save it.\n\nText and Markdown saves pass `reacquireExpiredLock: false`; they must not silently reacquire an expired lock and overwrite a changed file. Save acknowledges only the captured revision, preserving newer edits as dirty. The routed leave guard protects dirty navigation and pending operations. Text Close goes directly to the file list after release, and Discard commits a clean state before navigation so the guard doesn't prompt twice.\n\nSave from a valid active session can recreate a file deleted at the original path. It can also overwrite changes made at that path; it does not detect replacement files. Failed writes retain the draft. The dynamic host mounts one viewer, not a hidden candidate alongside the current document. Each viewer owns its load and error state; the image gallery reuses only its own local cache.\n\nRead-only disables typing, Save, and Replace, not Find, selection, copying, wrapping, download, or sharing. Recovery is resolved before automatic activation. Keep regressions for late acquisition, Strict Mode, read-only and conflict states, history navigation, and Markdown's separate lifecycle when changing this shared path.\n\n## Shared Viewer Notifications\n\n`ViewerNotifications.tsx` reuses the application notification host, shared edit-lock message mapping, and delayed acquisition indicator for text and Markdown. There is no viewer-corner or pane-local toast host in the file browser. Markdown retains its preview/edit lifecycle, but uses the same lock/read-only notification, filename badge, explicit Retry action, and retained-draft conflict decision. Lock release completes before another acquisition starts; obsolete acquisition results are released without publishing errors.\n\nEach viewer supplies active notices with stable IDs, severity, and operation occurrence numbers. One host displays one bottom-center toast across both panes and all viewer and page operations, prioritizing errors over warnings and information. Next notification exposes another pending condition. Dismissed heartbeat and draft-storage conditions stay dismissed until resolution or a changed condition. A new operation failure can notify again even when its message is unchanged. Resolved notices leave the active set, and source identities isolate dismissal state between files. Moving the host into a modal does not reset dismissal state.\n\nAll Text and Markdown editor toasts expire after 15 seconds, including informational lock notices, edit and save errors, print errors, heartbeat warnings, and draft-storage warnings. Hover or keyboard focus pauses expiry. Expiry hides only the notification; it does not clear the error, release a lock, discard a draft, or change the edit session. There is no additional inline warning after expiry. Existing editor controls and unsaved-change safeguards remain available. Toasts don't take focus or change document geometry. Recovery and unsaved-changes dialogs retain their own failure notices and suppress viewer toasts while open. Document-load failures, file-size limits, search validation, and editor-load/crash recovery remain in context rather than moving into the toast queue.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nPhysical streams read their first chunk before sending response headers. An initial read failure can therefore return a safe structured error. A later read failure terminates the stream and closes the backend; it cannot replace an already committed HTTP response with JSON. PDF derivative preparation reads its source before returning bytes, so a source failure during that buffered read can still use the structured error boundary. Native-download intent redemption uses the same prepared-stream boundary.\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### PDF Loading And Password Cancellation\n\nThe PDF viewer keeps the document hidden and its controls disabled until the active page's canvas has rendered. The loading indicator and text appear only after 500 ms. A fast load shows neither. Each new document, retry, or compatibility attempt starts a new feedback delay. Readiness does not wait for text extraction or a minimum indicator display time.\n\nEscape, Cancel, and the mobile back action in the password dialog cancel the current PDF load. Cancellation clears the password, unmounts the document to destroy its PDF.js loading task, releases its blob URL, and shows a notice with Retry. It does not submit an empty or null password, and it does not request compatibility processing. Downloading the original remains available through the viewer's existing download action. Only an explicit retry can start a new password request after cancellation.\n\nPassword callbacks belong to one load session. The viewer ignores callbacks from canceled or replaced sessions. An incorrect password can request another attempt within the same active session.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation. Its text-layer markers use `frontend/src/utils/domTextSearch.ts`.\n- Rendered Markdown uses a preview-owned session in `frontend/src/utils/viewportDomTextSearch.ts`. It reuses the DOM index and matcher from `domTextSearch.ts`, preserving rendered-text boundaries, cross-inline matches and exact code whitespace.\n- Markdown edit mode doesn't reuse the rendered-view DOM search implementation. It bridges the same outer toolbar UI into the editor-specific search state and commands instead.\n\nThe Markdown preview separates logical matches from their presentation. It retains exact match positions and text-node mappings, but paints at most 1,000 viewport search ranges plus one active-match range through CSS Highlights. Search doesn't insert markers, split text nodes or replace preview content. Navigation resolves the destination directly from the index and scrolls the content viewport, including for off-screen matches.\n\nEach preview generation owns its search session. Query changes reuse the unchanged DOM index; text replacement or character-data changes invalidate it. Syntax painting and theme-variable changes don't invalidate it. Scroll, resize, image loading and font readiness refresh presentation without matching the document again. Disposing the preview removes its highlights, style, observers, listeners, cached text and pending animation frame. PDF search remains independent.\n\nDOM capture collects text chunks and joins them once, preserving numeric offsets and block separators without repeatedly flattening the growing source. Syntax publication separately caps its viewport ranges and clips horizontally overflowing unwrapped code to visible columns. Both search and syntax skip vertical character-range lookup when the owning text box is wholly inside the viewport; partially clipped boxes retain exact boundary lookup. Horizontal clipping is independent of that fast path: the left lookup can stop at the first character, and the right lookup reuses the exact left boundary as its lower bound. Disjoint horizontal clips produce no ranges. These optimizations don't estimate character widths or cache geometry. Nested code-block scrolling refreshes syntax and search ranges without changing the source or search index.\n\nSearch highlight colors inherit the preview's scoped theme variables. Browsers without CSS Highlights retain counts and indexed navigation without visual search highlighting; the viewer logs that limitation rather than falling back to whole-document marker insertion. Browser support and whole-viewer performance acceptance remain separate rollout gates. Cached indexing doesn't guarantee responsive capture or rendering for arbitrarily large documents.\n\nUse the existing production-viewer check in `frontend/e2e/markdown-viewer.spec.ts` to attribute performance within the ReactMarkdown path. Its User Timing entries separate preview-search lookup, geometry, scrolling and publication from syntax mapping, geometry, range construction and publication. Geometry reads may force layout; registry calls can include native browser work, but don't necessarily include deferred painting. Worker round trips include transfer and acknowledgements, not just parsing. Source-response, DOM-commit-observer and frame milestones narrow initial-load costs without claiming isolated React CPU or hardware input-to-visible-paint latency. Functional passes don't establish the responsiveness budgets.\n\nInitial-load Markdown normalization uses the shared helper in `frontend/src/utils/markdownCodePreparation.ts`. Documents of at most 4,096 UTF-16 units run the existing canonical normalizer directly, avoiding worker startup and transport for small notes. This bounded path returns the same canonical text and prepared MDAST; it doesn't skip normalization or change rendering. The size limit lives in the shared preparation protocol. Larger documents each own a preparation worker and transfer source, canonical text and an equivalent canonical MDAST in acknowledged, bounded chunks. Tree batches contain at most 512 records and 16,384 string UTF-16 units; individual field pieces are at most 2,048 units. Numeric/flag/position metadata is validated separately, and large text and table alignment fields use the chunk channel instead of content limits. Host acknowledgements yield between tree batches. Success, cancellation, decode failure and timeout terminate the worker; aborted loads can't publish content. Worker failures use the existing load-error path without a synchronous retry, and local preparation failures aren't reported as server overload. The pre-app capability gate requires a callable Web Worker API and otherwise shows the existing unsupported-browser screen without importing the app. The helper retains defensive synchronous normalization with a diagnostic for larger documents when workers are unavailable, but Worker-less app operation isn't supported. API presence doesn't guarantee successful worker construction or execution; existing startup, timeout, crash and decode-error handling remains necessary. The shared protocol is DOM-free. Vite's shared resolver aliases the character decoder to its non-DOM implementation before dependency optimization, so development and production workers use the same implementation. A worker-build-only resolver isn't sufficient for development's prebundled dependencies.\n\nReactMarkdown remains the only application whole-document renderer in every build mode. Its parser hook reuses a defensive clone of the prepared tree only when the tree matches the preview generation's exact source. All normal remark transforms, GFM, table-cell break handling, safe URL/raw HTML behavior and React rendering remain in that path. Cloning prevents those transforms from mutating the retained canonical tree. A successful Save that changes the source releases the superseded tree; edited content without a matching tree uses the normal parser.\n\nRendered Markdown sources of at least 50,000 UTF-16 units use `ProgressiveMarkdown` to append the existing pipeline's fully transformed output. Document-wide references, headings and GFM are resolved once before staging. Chunks aren't parsed as independent Markdown documents. Ordinary sources keep their immediate rendering path. Staged batches use the same ReactMarkdown rendering and safe-link/raw-HTML handling, with at most 1,024 structural nodes or 8,192 text units. Oversized tables, containers and code blocks are subdivided internally, preserving one native table or code block rather than splitting it into separate documents. Already-published nodes aren't replaced by later appends.\n\nThe viewer targets two viewport heights for the initial fill, then yields. Later frames use the 4 ms elapsed-work target without a height limit or repeated per-batch geometry reads. Each frame commits at most four batches, checking elapsed time after every commit to bound work accumulated before native layout. Neither the fill target nor these limits guarantee a maximum task duration: whole-document cloning/transforms, a single commit and native layout remain synchronous. Visible pages use animation frames; hidden pages use timers so completion doesn't wait indefinitely for a frame. Source or rendering-configuration changes and disposal cancel the old publication owner; a restarted generation resets document readiness. A 200 ms delayed, accessible loading indicator disappears immediately on completion and respects reduced motion.\n\nReading published text and closing the viewer remain available during progressive loading. Document search/counts, editing, heading-link navigation and toolbar printing wait for complete publication; syntax painting and DOM search indexing also wait. Browser-menu printing while loading shows a loading notice instead of partial document content. Once complete, normal native selection, search, links and print behavior apply. These controls prevent partial results from being presented as complete; they don't promise that synchronous preparation can never block input.\n\nMarkdown editing reuses the preparation worker for full-document canonical normalization when the editor source contains `\u003cbr`. The existing no-`\u003cbr` typing path still publishes immediately without normalization. If both the original baseline and edited document contain possible table syntax, a background preservation-only job compares their tables without changing that typing normalization policy. Identical sources or documents without a pipe character need no table comparison. Each editor owns at most one active job and one replaceable latest request. Only the current source, baseline, policy and generation can satisfy a prepared snapshot; obsolete success, failure and diagnostic messages are ignored. Worker acknowledgements never replace the native CodeMirror document, recreate table-cell editors or change transaction history. Pending table/IME publication and worker preparation keep the viewer dirty independently of canonical draft publication. External source changes and unmount dispose the old owner and its workers; a baseline change invalidates unmatched prepared bytes.\n\nToolbar Save takes focus before its click handler captures selection. The rich editor therefore remembers the active nested table cell on native focus entry and departure, and refreshes that snapshot when selection is explicitly preserved inside the editor. Stay-edit Save restores the same connected cell within the current root instead of focusing the root and triggering native table-widget reconstruction. If the cell document changed while Save was pending, restoration keeps its newer native selection rather than replaying old offsets. Returning to root-text editing, replacing the external document and unmounting clear the remembered cell; disconnected or replaced cells use the existing root-selection fallback. This doesn't change native transactions, history grouping or composition handling. Production checks require retained cell identity/focus after Save, continued typing, and native undo/redo; these functional checks don't establish responsiveness acceptance.\n\nAsync snapshot capture flushes table/IME publication and worker preparation within the existing transition deadline. It requires full-document normalization even after the typing fast path, so Save retains list, escape and table canonicalization. The same worker performs the unchanged AST-aware table comparison against the exact original baseline, preserving original source for semantically unchanged tables. Source and baseline transfer sequentially in acknowledged chunks of at most 16,384 UTF-16 units, with generation and sequence validation; result chunks retain the same bound. Edit preparation doesn't request a preview tree, whose offsets would no longer match preserved source. Save consumes immutable, complete source-preserving snapshot bytes; repeated serialization returns the captured string without parsing. A successful write acknowledges only its snapshot: newer pending edits stay dirty, and an unavailable newer snapshot doesn't turn the completed write into a failure. Worker failure preserves editing and dirty content; a subsequent explicit async snapshot request can retry, but failures never trigger a synchronous parsing fallback or an automatic retry loop.\n\nSynchronous snapshot capture and canonical getters reject pending or failed worker preparation, including an unmatched source-preservation baseline, rather than returning an older revision as current. Recovery retains its synchronous pagehide/pre-sign-in attempts, debounce and limits; failed capture logs the failure and shows the existing recovery warning. It doesn't mark content saved. Native text sharing is unavailable while publication is pending and reads a complete snapshot when ready. Worker-side normalization and source preservation don't establish whole-viewer timing or resource acceptance; native table editing, layout and preview reconstruction remain separately measured costs.\n\nThe bounded `sambee:edit-preparation:*` entries separate queue wait, worker startup/first acknowledgement, source and baseline transfers, run-to-first-result, result delivery, total transport/job time and complete async snapshot flush. Numeric metadata records generation, source/baseline lengths, policy, chunk counts and whether a completed job is current or obsolete; it contains no source text. Transport completion also reports worker normalization and source-preservation durations separately. Host intervals include event-loop scheduling and acknowledgement delays, so startup isn't isolated worker boot time and transfer isn't pure wire time. Worker durations aren't main-thread CPU, and nested intervals mustn't be added to their enclosing job or snapshot flush. Each stage retains only its latest entry; the existing test observer collects individual samples. Use these measurements to distinguish Save wait from the native table/focus work that can follow write acknowledgement, not to infer a faster Save or passing keyboard/paint budgets from worker offload alone.\n\nThe bounded `sambee:preview-preparation:*` entries separate asynchronous decode elapsed time, load normalization, tree cloning, code-block collection and ReactMarkdown transforms. For worker-backed loads, `load-normalization-elapsed` includes worker startup, transfer, work, host tree assembly, acknowledgements and scheduling, not main-thread CPU time. For small notes, it measures direct canonical normalization and prepared-tree creation. `render-prepared-tree` measures the defensive clone; `render-parse` measures normal parsing when no matching tree is available. The initial-load production matrix requires the clone stage and rejects synchronous `render-parse` and standalone `collection-parse` stages. Live syntax request collection walks the renderer's existing tree; it doesn't parse source again or change markup. The `collection-walk` interval is included in `render-transform`, not additional time to sum. Each generation publishes its ordered requests after DOM commit, before the passive syntax preparation effect, which snapshots them and retains cancellation and stale-generation guards.\n\nThe HAST-ready-to-layout-effect interval includes element construction, reconciliation, commit and scheduling, not just React CPU or paint. Entries contain no source text; each stage retains its latest measurement while the browser test observer collects individual samples. Normalization reuses its parsed tree when canonicalization leaves the source unchanged and reparses in the same preparation path when edits change source offsets. Tree reuse doesn't close responsiveness, retained-memory, syntax-completion or native interaction acceptance.\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Single-Renderer Acceptance\n\nThe retained whole-document viewer integration and its special build-mode selection have been removed. Don't reconnect the historical publisher or add a second renderer to finish shared highlighting. Reuse ReactMarkdown, its parsed-tree code collection, the existing workers and viewport CSS highlights. Standalone renderer proofs are historical research, not application acceptance or a delivery dependency.\n\nRun `npm run build`, then `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production syntax publication' --workers=1 --repeat-each=3` from `frontend/`. The existing matrix uses the approved demo connection and unchanged dense, near-safeguard, host-envelope, many-block and long-line fixtures in Chromium and Firefox at desktop and narrow widths. Add `PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-reactmarkdown-baseline.json` and `--reporter=json` to retain structured reports without npm's console preamble. Each fixture attaches `viewer-timing-budgets.json`, with observed values, numeric targets, pass/fail results and criteria that remain unmeasured.\n\nThe timing gate evaluates file-click-to-text-completion, first exact search, changed query, last-match navigation and maximum viewer timer-service gap. Missing, non-finite or negative samples fail every run; `SAMBEE_E2E_BUDGETS=1` also fails over-budget samples. Omit that flag for functional-only runs, which still attach the budget result. Forced-GC and tracing runs are marked diagnostic and can't enforce timing acceptance. Run `npm run test -- src/utils/__tests__/viewerPerformanceBudgets.test.ts` from `frontend/` for the evaluator's boundary and error tests. These browser-independent checks also run in the normal Vitest CI suite, without repeating them for each browser project. To validate a recorded report, the existing Playwright entry point remains available: `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_REPORT=/tmp/report.json SAMBEE_E2E_SLICE=publication npm run test:e2e -- viewer-performance-budgets.spec.ts --workers=1`.\n\nSearch/query/navigation probes start in browser event handlers, observe the expected count and active highlight in the existing small search controls, and finish after two frames. They avoid page-wide text queries and Playwright round-trip timing, but aren't hardware input-to-visible-paint measurements. The existing active-search fixture deliberately holds syntax preparation; text-load completion doesn't include syntax. Fresh/cached grammar isolation, first usable text/highlight completion, source editing, large prose/tables, resource acceptance and native interaction still require their own evidence. A passing timing subset isn't full rollout acceptance.\n\nThe browser checks compare exact rendered text, native Select All, selected code text and accessibility-tree output. They also exercise keyboard focus, safe links/HTML, GFM tables/tasks, shared Find navigation, theme-variable updates without text-node replacement, native copy events and Chromium PDF generation. These don't establish OS clipboard payloads, browser-native Find reveal, assistive-technology behavior or visual full-document print/PDF correctness. Those remain manual gates.\n\nThe separate native-constraint slice checks representative multiline, long-line and nested Markdown at widths 1543/390 in Chromium/Firefox. It compares cross-block selected text with a trusted keyboard copy/paste payload, exercises keyboard focus and native `window.find` selection/reveal, and attaches real Chromium PDFs. The native text-find API isn't the browser Find toolbar, and a narrow desktop viewport isn't a physical phone. From `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-native-constraints.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production native Markdown constraints' --workers=1 --reporter=json\n```\n\nFrom the repository root, check the attached PDF text with the existing backend environment:\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-native-constraints.json\n```\n\nThe checker rejects missing/duplicate PDF cases, unsuccessful browser results and missing rendered-document lines. Heading IDs use a safe prefix and standard duplicate/Unicode slugging in the existing HAST pipeline; matching fragments are rewritten consistently. Native and printing matrices have independent checks. Chromium's `window.find` reveal is diagnostic-only because it can select without scrolling even outside Sambee; exact selection remains required in both engines, and Firefox reveal remains enforced. Don't add application scrolling to manufacture a native Find pass.\n\nThe Markdown preview's Print icon calls the native browser print dialog; Save as PDF is a destination in that dialog, not a second renderer or server-side conversion. Print isn't offered in edit mode or enabled while loading has failed or is incomplete. Print-only styles hide controls/background UI, release fullscreen/scroll constraints, wrap code/table cells, retain images and use black text on white regardless of the screen theme. Native `beforeprint`/`afterprint` handlers preserve focus, selection and nested scroll, with pending callbacks removed on disposal. The fullscreen paper sizes against its fixed container rather than dynamic viewport units that can retain print-page dimensions.\n\nRun the independent print matrix from `frontend/`, then inspect the PDF attachments from the repository root:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-markdown-printing.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production Markdown printing' --workers=1 --reporter=json\n```\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-markdown-printing.json --printing\n```\n\nThe 24-case matrix covers three fixtures, both themes, both widths and both engines. It verifies action invocation, print CSS, wrapping/widths and actual Chromium PDF state restoration. The PDF gate requires all 12 Chromium outputs to contain every rendered non-whitespace text line and an embedded image. Clear any forced screen-media override before PDF generation; otherwise Playwright prints screen CSS. First/last-page raster inspection supplements text checks. Firefox CSS checks aren't actual Firefox PDF evidence. Actual Firefox PDF and desktop/physical printing were separately confirmed complete by the user on 2026-10-24; no detailed browser/printer support matrix is inferred. Browser destination, paper, margin and header/footer settings remain user-controlled.\n\nKeep performance changes local to measured costs in the current path. Distinguish first visible syntax from completion of all block preparation, and include serialization and parent updates when measuring typing or atomic replace-all. Configuration-only theme and grammar updates must not request caret reveal or replace the document, selection or editor. Don't add streaming, scheduling abstractions or new edit protocols without evidence that the existing path misses its target.\n\nThe existing viewer harness also has a `production source responsiveness` slice for the 54,000-unit dense and 6,000-match long-line source fixtures. It verifies bounded worker delivery, one atomic replacement, undo/redo, exact saved file bytes and worker termination. Save assertions decode the complete multipart body received by the isolated test HTTP proxy; Playwright's request snapshot can omit uploaded file bytes. All traffic uses fixtures, never stored demo edits.\n\nLarge Replace All operations may temporarily block the editor while CodeMirror applies their atomic change set. This latency is an accepted limitation under D5, not permission to truncate output, split history or replace the entire document instead of preserving logical changes. Text and Markdown editors share an editor-owned indeterminate replacement indicator. Worker preparation shows it only after 200 ms; completion before that threshold cancels it without a flash. Ordinary literal replacements stay synchronous and aren't given an artificial delay.\n\nBefore a known-heavy apply, the indicator is shown and given two animation-frame callbacks so the browser has a paint opportunity before the native dispatch. The conservative workload gate requires at least 1,000 replacements and at least 50,000 UTF-16 units in the source or inserted payload. Literal commands inspect at most 1,000 matches for this estimate; worker commands use the completed change plan. This isn't a duration prediction: some fast workloads may be classified as heavy, and unexpectedly slow synchronous work cannot reveal a delayed indicator while blocking the main thread. Feedback already visible during preparation also receives a paint opportunity before application. There's no minimum visible duration or delayed completion, and the spinner doesn't promise continued animation or input responsiveness during synchronous apply.\n\nThe same command boundary covers toolbar and keyboard Replace All. Pending replacements reject duplicate invocations. Any introduced yield revalidates the exact document, query, selection and writability; editing or switching state cancels obsolete work rather than applying stale replacements. Failure, timeout, cancellation and editor disposal release the indicator, animation, timers and listeners. Hidden documents don't wait indefinitely for throttled animation frames. The status uses the editor theme, exposes accessible busy/status semantics and respects reduced motion; physical assistive-technology behavior remains a separate manual check.\n\nThe `production replacement feedback` slice checks quick no-flash behavior and captures visible feedback with the original source still present, then releases held frames and verifies atomic undo/redo, exact multipart Save and editor cleanup in both engines at widths 1543/390. Its held-frame evidence is functional, not timing acceptance.\n\nSource edits retain one bounded User Timing entry per stage: `sambee:source-editor:serialize`, `sambee:source-editor:publish`, `sambee:source-editor:normalize` and `sambee:source-editor:parent-update`. The enclosing publication includes normalization and the synchronous parent callback. These overlapping stages mustn't be added together. Entries contain lengths/revisions, not document contents. `sambee:source-search:commit` brackets the native atomic dispatch, including its synchronous listeners; deferred React work isn't isolated CPU time inside that measure. The separate click-to-completion probe waits for the parent dirty-state render and two subsequent frames. That boundary is a scheduling proxy, not hardware paint.\n\nFrom `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-responsiveness.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nEach sample attaches source-private measurements and explicit 50 ms atomic-dispatch, enclosing serialization/publication and maximum-timer-gap checks. Missing or invalid evidence fails even without `SAMBEE_E2E_BUDGETS`; that flag additionally enforces the original limits. Retain the failed native atomic-application timing results as diagnostic evidence of the D5 accepted limitation, not as passing samples or a reason to repeat performance-only matrices. Unrelated source timing, worker correctness and resource gates remain required. Transfer counts aren't retained/peak memory evidence, and these fixtures don't establish sustained typing, large-table normalization, dense output expansion or scrolling acceptance.\n\nThe separate `production source typing` slice types 82 characters at a requested 10 ms inter-key delay into each 54,000-unit fixture, without per-key polling. It records trusted browser keydown-to-first/two-frame samples, timer gaps, all four edit stages and optional whole-renderer Long Tasks entries, then verifies exact saved source plus the payload. The `source-typing` attachment enforces two-frame p95 strictly below 50 ms and stage/gap maxima at most 50 ms. All 24 engine/width/repeat trials pass; the worst per-trial p95 is 35 ms. This is a scheduling proxy, not physical input-to-painted-pixel acceptance. Unsupported Long Tasks capability stays unmeasured, and observed tasks wouldn't establish application-owned CPU attribution.\n\nThe `production prose table responsiveness` slice mounts the approved 4,000 formatted paragraphs or 2,400 two-column table rows. It checks every rendered paragraph/cell exactly, preserves native block whitespace, root/text-node identity and full rendered text through 60 programmatic scroll steps, and verifies cross-block native selection and close cleanup. Load timing runs from the browser's file-open click through two frames after all expected blocks mount. The `prose-table-responsiveness` attachment separates load budgets, the earlier two-viewport geometry milestone and diagnostic rAF scroll intervals, including the frame following the final scroll assignment. The final 24 trials complete within 1,110 ms, with the first viewport available within 761 ms. Nineteen trials exceed the unchanged 50 ms timer-gap limit, with a worst gap of 128 ms. These recorded loading pauses are accepted under D6, not passing timing samples or isolated CPU attribution. Headless rAF intervals don't establish physical refresh rate, wheel/touch, compositor or painted-frame acceptance. These fixtures have no fenced syntax and don't measure syntax readiness or large-table source normalization.\n\nThe separate `production progressive Markdown loading cancellation` slice holds frame callbacks after two viewport heights exist. It requires visible feedback, disabled document controls, loading-only print output and a working Close action, then releases stale callbacks and verifies complete reopening. It runs in Chromium and Firefox at widths 1543/390. Its paused screenshots and functional passes aren't timing evidence. The existing large-code publication, native interaction and print matrices remain independent regression checks; their completion and acceptance boundaries are recorded below.\n\nRun these slices separately from forced GC and CPU profiling:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-typing.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source typing' --workers=1 --repeat-each=3 --reporter=json\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-prose-table-responsiveness-final.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production prose table responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nFor separate Chromium load attribution, select the same prose/table slice with `SAMBEE_E2E_TRACE=1` and no budget enforcement or forced GC. The `viewer-load-cpu-profile` and `viewer-load-timeline` attachments span file open through completed mounting; nonempty CPU samples and both `sambee:viewer-load:start`/`sambee:viewer-load:complete` timeline markers are required. Budget status is diagnostic, never acceptance. Two desktop captures show one preview build, with a 126.05 ms prose render callback and a 53.69 ms table callback before native style/layout. The prose clone, transforms and HAST-to-layout-effect stages take 38.3, 37.5 and 44.5 ms; these overlap the encompassing callback and mustn't be added to it. Prose native style/layout takes a further 21.14/38.13 ms. Keep cached-tree isolation and native document semantics; neither deleting the clone nor an unapproved publication/renderer change is justified by this evidence. Firefox/mobile CPU attribution remains unverified.\n\nChromium CPU sample deltas can be negative. Reconstruct cumulative sample timestamps, sort them, then clip nonoverlapping intervals to the load markers. Summing only positive deltas inflates CPU weights. Use the marker's renderer PID/thread for main-thread timeline attribution; worker processing and unclassified native samples aren't automatically application-owned blocking CPU.\n\nRepeated source-regex Next/Previous requests are queued in order while navigation is pending. The active navigation worker reuses its transferred document for that burst, applying each native CodeMirror command from the preceding result's selection with the current position's whole-word rules. It terminates when the queue drains; no idle worker is retained. Document/query changes, external selection changes, replacement commands, failures and disposal cancel obsolete queued navigation. Unit tests compare reused-worker navigation with native commands, including mixed directions, wraparound, overlapping matches and zero-length expressions.\n\nThe independent `production source regex parity` slice compares counts and exact saved output with the installed CodeMirror commands for zero-length lookahead, case-sensitive and whole-word matching. A replacement exceeding two source-transfer chunks verifies continuation assembly without truncation. `production source regex lifecycle` injects worker-construction, error/decode-event and startup-timeout failures, requires actionable feedback and a successful retry, and preserves continued editing and exact Save bytes. A partial-delivery case lets one replacement chunk arrive before cancellation, then replays stale change/completion messages; no partial replacement may be committed. These are host-side fault injections, not actual browser-process crash or structured-clone failure evidence. Run both functional slices with:\n\n```sh\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production source regex (parity|lifecycle)' --workers=1\n```\n\nFor optional source renderer footprint diagnostics, use `SAMBEE_E2E_MEMORY=1` without timing enforcement, select `production source responsiveness`, and run the Chromium-only `npm run test:e2e`. The `source-renderer-memory` attachment records CDP renderer heap after explicit GC at pre-open, counted-results, post-replacement and post-close boundaries. Its historical 64 MiB assertion isn't a release criterion under D11. These are whole-viewer post-GC observations, not isolated result-array bytes, peak/worker/native memory or proof of leak-free cleanup. Staged/peak-memory limits and a fixed close/reopen cycle protocol aren't required. The source budget status is diagnostic in memory mode.\n\nFor a separate Chromium CPU diagnostic, use `SAMBEE_E2E_TRACE=1` without `SAMBEE_E2E_BUDGETS=1`, restrict the grep to `production source responsiveness long-line at 1543px`, and run `npm run test:e2e`. The `source-dispatch-cpu-profile` attachment contains the CDP CPU profile; its source budget status is diagnostic, never an acceptance pass. The source slice rejects combined profiling/GC and either diagnostic mode combined with timing enforcement.\n\nFor separate controlled-memory trials, add `SAMBEE_E2E_MEMORY=1` and restrict the existing matrix to the many-block fixture and Chromium. Release harness-held node references before post-GC sampling. Renderer heap excludes worker heaps and aggregate/native memory; a single close isn't repeated-close leak acceptance. Keep forced GC separate from responsiveness timing.\n\nFor diagnostic scheduling traces, add `SAMBEE_E2E_TRACE=1` to a single-fixture Chromium run. The `viewer-scheduling-trace` attachment contains a CDP timeline and V8 CPU profile. Align `sambee:viewer-trace:start` with browser timestamps; join CPU chunks by renderer PID and profile ID and count samples once. Firefox native profiling must use content-process User Timing markers rather than parent-only samples. Profiling adds overhead and isn't acceptance timing.\n\nTo isolate native table input from application work, run the existing proof from `frontend/`:\n\n```sh\nSAMBEE_NATIVE_TABLE_REPORT=/tmp/sambee-native-table node scripts/source-search-containment-proof.mjs --native-table\n```\n\nThis uses public CodeMirror/Lezer and `markdownTables` APIs at the approved demo URL, with an isolated HTML response and default package styling. It edits the middle cell of the fixed 2,400-row table at 1543x900 without React, application CSS, normalization, Save or workers. It requires exact complete native source, atomic full-table replacement spans, native undo/redo and disposal. Native table source uses `\u003cbr\u003e`; application canonicalization to `\u003cbr /\u003e` isn't part of this proof. Root state materialization and view-update intervals are reported separately; input-to-root includes scheduling and deferred publication, not just model CPU. The unminified desktop diagnostic isn't a production acceptance trial or a replacement for mobile, composition and lifecycle checks.\n\nThe optional report prefix writes per-engine JSON and the exact diagnostic bundle. For separate profiling, add `SAMBEE_E2E_TRACE=1` and configure `MOZ_PROFILER_STARTUP=1`, `MOZ_PROFILER_STARTUP_FILTERS=GeckoMain`, `MOZ_PROFILER_STARTUP_FEATURES=js,stackwalk,leaf` and `MOZ_PROFILER_SHUTDOWN` with an absolute output path. Chromium records input-only CPU samples; clip Firefox content-process samples between `sambee:native-table:input-start` and `sambee:native-table:input-end`, excluding construction and history checks. Profiling requires a report prefix and Firefox startup configuration; product-budget enforcement and controlled-GC modes are rejected. Inclusive model, parsing and native reflow samples overlap and mustn't be summed. Unclassified Chromium native samples aren't automatically package JavaScript CPU. Slow native input doesn't by itself establish slow atomic state application or justify private package patches, changed history, wrapping or selection semantics.\n\nCount assertions remain scoped to the existing search controls to avoid page-wide Playwright text caches inside measurement windows. Results are labelled `scoped-controls-v2`; older input figures aren't directly comparable. Handler-to-frame samples and synthetic event age don't establish hardware input-to-visible-paint latency. Removing the alternate renderer doesn't close any performance, memory or manual interaction gate.\n\n### Shared Highlighting Acceptance And Limitations\n\nThe shared-highlighting implementation was approved by the user for merge and rollout on 2026-10-24. Approval doesn't turn failed measurements into passes or establish support for untested devices. Keep original targets, raw verdicts and these scoped acceptance decisions together:\n\n| Decision | Accepted scope | Boundaries |\n|---|---|---|\n| D5 | Noticeable large atomic Replace All latency with visible busy feedback. | Preserve complete output, logical change mapping, one native transaction and undo/redo. Unrelated source-search or typing pauses aren't accepted by this decision. |\n| D6 | The recorded progressive prose/table preview-loading pauses: 19/24 trials above 50 ms, worst 128 ms; all complete within 1,110 ms. | These remain failed gap samples. Longer future delays and other workloads aren't covered. Asynchronous preview preparation remains declined. |\n| D8 | Responsiveness limitations of the existing Markdown table editor. | Table-component timing is diagnostic and non-blocking; exact input, Save, composition, history and cleanup remain required. |\n| D9 | Ten recorded Firefox many-block syntax-color samples at 1,511-1,579 ms against the 1,500 ms target. | All 120 cold/warm samples were collected; 110 meet that target. Full syntax preparation stays within 3,000 ms. No broader delay exception is implied. |\n| D10 | Four recorded Firefox desktop code-display gaps at 51-59 ms against 50 ms. | Preserve the raw failures. Additional delayed-image/font/resize and scroll-anchor test coverage was removed, not passed. Correct content, selection and scrolling remain required. |\n| D11 | Leak investigation and fixes for demonstrated unwanted retention, rather than quantitative memory acceptance. | Staged/peak-memory limits and fixed-cycle shutdown checks were removed, not passed. No exhaustive leak-free claim is made. |\n| D12 | Removal of real-phone and physical keyboard/IME acceptance, including phone print UI and hardware-response measurements. | This isn't verified device support. Automated keyboard/composition, exact editing/Save/recovery and desktop native/print correctness remain required. |\n\nBrowser-menu Find/reveal, OS clipboard, assistive-technology and physical-scrolling checks were confirmed complete by the user on 2026-10-23. Remaining Firefox PDF and desktop/physical printing checks were confirmed complete on 2026-10-24. These are user confirmations, not new automated measurements or a detailed device, browser, AT or printer support matrix. Don't reopen completed checks or rerun accepted timing failures solely to close a checklist; retest affected behavior after a relevant change or demonstrated regression.\n\nThe final editing checks cover theme changes followed by editing exit and Close, late worker results, distinct documents, captured-revision Save with newer dirty edits, failed writes and recovery/snapshot failures. Source-regex terminal cleanup detaches worker handlers, releases terminated workers and clears obsolete replacement buffers, while retaining buffers needed for a pending atomic apply. Ownership review and lifecycle assertions establish the investigated cleanup, not a heap-retention proof for every browser object.\n\nUse `PLAYWRIGHT_JSON_OUTPUT_FILE`, not `PLAYWRIGHT_JSON_OUTPUT_NAME`, for an explicit report path with the JSON reporter. Preserve complete identities, both engines, widths 1543/390, original workloads and three trials per timing identity. Recorded-report evaluation must retain failed samples and reject missing, duplicate, invalid, skipped or retried identities. Functional-only runs and tracing/GC diagnostics don't establish timing passes. Retain local reports before temporary-file cleanup; overlapping runs aren't additive test totals.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. Dedicated formats need a coordinated backend/frontend contract update. Languages already present in the shared CodeMirror catalogue need no separate extension registration for text opening; extra frontend entries are only needed for MIME or presentation metadata.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/fileLanguages.ts` | reuse shared language filename matching; maintain additional plain-text extensions here rather than duplicating language extensions |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare dedicated viewers and optional MIME/presentation metadata; text-viewer assignments are derived automatically |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or the unified `TextEditor`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npm run typecheck\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.8": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.9": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "1.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "2.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must agree on image formats, conversion requirements, and MIME types used for dedicated viewers\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/fileLanguages.ts` | shared CodeMirror language catalogue, filename matching, and additional plain-text extensions used by highlighting and default text opening |\n| `frontend/src/utils/FileTypeRegistry.ts` | dedicated viewer mappings and MIME/presentation metadata; derives text-editor support from shared filename recognition |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nDedicated formats such as images require backend and frontend agreement. Text-file recognition instead uses `fileLanguages.ts`: both highlighting and default text opening consume the same CodeMirror catalogue. Language metadata doesn't load a grammar or import the highlighting core into the file browser.\n\nExplicit image, PDF, and Markdown viewers take precedence over extension-based text recognition. A recognized, non-generic MIME type with a viewer mapping takes precedence over the filename; empty MIME types, `application/octet-stream`, and `text/plain` fall back to filename recognition. Saved viewer preferences override the default selection. Unknown files still use the viewer picker unless a MIME mapping or saved preference selects a viewer.\n\nAll file viewers and editors use `useViewerDocumentTitle` to set the browser tab title to the active filename, including its extension. Image navigation updates the title to the active image. Native print events temporarily remove the final extension so browsers can suggest a clean PDF filename. The Markdown Print action uses the hook's print callback to prepare the title before opening the dialog and restore it after a print failure. Successful calls retain the short title until `afterprint`; `window.print()` can return before the print dialog closes. Closing the workspace restores the previous title unless another owner has changed it.\n\n## Unified Text Editor\n\n`TextEditor.tsx` owns the text destination and reuses `TextCodeEditor` for writable and read-only content. There isn't a separate text-viewer component or an Edit action. The public `viewer=text` identifier, viewer preferences, settings, and recovery-draft keys remain compatible. Text routes accept absent, `view`, and `edit` modes as the same destination; canonical URLs omit `mode` without adding a history entry or dropping fragments. Markdown still uses its existing preview/edit route modes.\n\nOpening an eligible text file automatically calls `beginViewerTextEdit`. The editor stays read-only until acquisition succeeds and a fresh content read establishes the baseline. Archive members, read-only connections, and oversized files don't acquire sessions. Storage boundaries distinguish contention, denied permissions, unsupported editing, and temporary unavailability. SMB's acquisition request opts into a non-mutating per-file write probe; Companion also checks an existing file with read/write open and no creation or truncation.\n\nAcquisition feedback appears after 200 ms as a small spinner beside the filename, in a fixed-size toolbar slot. Fast acquisitions show no progress message, and slower ones don't move the document. Completion, navigation, and unmount cancel pending feedback without delaying readiness. Access failures remain immediate; related error details and the read-only reason share one notice with Retry where supported.\n\nAcquisition uses an activation generation to release obsolete results, and a pending release completes before another acquisition starts. Confirmed lock loss or revoked access freezes mutations and retains the draft; a transient heartbeat failure shows a warning. Retry is explicit, not an acquisition loop. A fresh baseline that differs from a retained draft's original baseline requires a conflict decision before editing resumes. Choosing the draft doesn't save it.\n\nText and Markdown saves pass `reacquireExpiredLock: false`; they must not silently reacquire an expired lock and overwrite a changed file. Save acknowledges only the captured revision, preserving newer edits as dirty. The routed leave guard protects dirty navigation and pending operations. Text Close goes directly to the file list after release, and Discard commits a clean state before navigation so the guard doesn't prompt twice.\n\nSave from a valid active session can recreate a file deleted at the original path. It can also overwrite changes made at that path; it does not detect replacement files. Failed writes retain the draft. The dynamic host mounts one viewer, not a hidden candidate alongside the current document. Each viewer owns its load and error state; the image gallery reuses only its own local cache.\n\nRead-only disables typing, Save, and Replace, not Find, selection, copying, wrapping, download, or sharing. Recovery is resolved before automatic activation. Keep regressions for late acquisition, Strict Mode, read-only and conflict states, history navigation, and Markdown's separate lifecycle when changing this shared path.\n\n## Shared Viewer Notifications\n\n`ViewerNotifications.tsx` reuses the application notification host, shared edit-lock message mapping, and delayed acquisition indicator for text and Markdown. There is no viewer-corner or pane-local toast host in the file browser. Markdown retains its preview/edit lifecycle, but uses the same lock/read-only notification, filename badge, explicit Retry action, and retained-draft conflict decision. Lock release completes before another acquisition starts; obsolete acquisition results are released without publishing errors.\n\nEach viewer supplies active notices with stable IDs, severity, and operation occurrence numbers. One host displays one bottom-center toast across both panes and all viewer and page operations, prioritizing errors over warnings and information. Next notification exposes another pending condition. Dismissed heartbeat and draft-storage conditions stay dismissed until resolution or a changed condition. A new operation failure can notify again even when its message is unchanged. Resolved notices leave the active set, and source identities isolate dismissal state between files. Moving the host into a modal does not reset dismissal state.\n\nAll Text and Markdown editor toasts expire after 15 seconds, including informational lock notices, edit and save errors, print errors, heartbeat warnings, and draft-storage warnings. Hover or keyboard focus pauses expiry. Expiry hides only the notification; it does not clear the error, release a lock, discard a draft, or change the edit session. There is no additional inline warning after expiry. Existing editor controls and unsaved-change safeguards remain available. Toasts don't take focus or change document geometry. Recovery and unsaved-changes dialogs retain their own failure notices and suppress viewer toasts while open. Document-load failures, file-size limits, search validation, and editor-load/crash recovery remain in context rather than moving into the toast queue.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nPhysical streams read their first chunk before sending response headers. An initial read failure can therefore return a safe structured error. A later read failure terminates the stream and closes the backend; it cannot replace an already committed HTTP response with JSON. PDF derivative preparation reads its source before returning bytes, so a source failure during that buffered read can still use the structured error boundary. Native-download intent redemption uses the same prepared-stream boundary.\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nCommon errors include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### PDF Loading And Password Cancellation\n\nThe PDF viewer keeps the document hidden and its controls disabled until the active page's canvas has rendered. The loading indicator and text appear only after 500 ms. A fast load shows neither. Each new document, retry, or compatibility attempt starts a new feedback delay. Readiness does not wait for text extraction or a minimum indicator display time.\n\nEscape, Cancel, and the mobile back action in the password dialog cancel the current PDF load. Cancellation clears the password, unmounts the document to destroy its PDF.js loading task, releases its blob URL, and shows a notice with Retry. It does not submit an empty or null password, and it does not request compatibility processing. Downloading the original remains available through the viewer's existing download action. Only an explicit retry can start a new password request after cancellation.\n\nPassword callbacks belong to one load session. The viewer ignores callbacks from canceled or replaced sessions. An incorrect password can request another attempt within the same active session.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation. Its text-layer markers use `frontend/src/utils/domTextSearch.ts`.\n- Rendered Markdown uses a preview-owned session in `frontend/src/utils/viewportDomTextSearch.ts`. It reuses the DOM index and matcher from `domTextSearch.ts`, preserving rendered-text boundaries, cross-inline matches and exact code whitespace.\n- Markdown edit mode doesn't reuse the rendered-view DOM search implementation. It bridges the same outer toolbar UI into the editor-specific search state and commands instead.\n\nThe Markdown preview separates logical matches from their presentation. It retains exact match positions and text-node mappings, but paints at most 1,000 viewport search ranges plus one active-match range through CSS Highlights. Search doesn't insert markers, split text nodes or replace preview content. Navigation resolves the destination directly from the index and scrolls the content viewport, including for off-screen matches.\n\nEach preview generation owns its search session. Query changes reuse the unchanged DOM index; text replacement or character-data changes invalidate it. Syntax painting and theme-variable changes don't invalidate it. Scroll, resize, image loading and font readiness refresh presentation without matching the document again. Disposing the preview removes its highlights, style, observers, listeners, cached text and pending animation frame. PDF search remains independent.\n\nDOM capture collects text chunks and joins them once, preserving numeric offsets and block separators without repeatedly flattening the growing source. Syntax publication separately caps its viewport ranges and clips horizontally overflowing unwrapped code to visible columns. Both search and syntax skip vertical character-range lookup when the owning text box is wholly inside the viewport; partially clipped boxes retain exact boundary lookup. Horizontal clipping is independent of that fast path: the left lookup can stop at the first character, and the right lookup reuses the exact left boundary as its lower bound. Disjoint horizontal clips produce no ranges. These optimizations don't estimate character widths or cache geometry. Nested code-block scrolling refreshes syntax and search ranges without changing the source or search index.\n\nSearch highlight colors inherit the preview's scoped theme variables. Browsers without CSS Highlights retain counts and indexed navigation without visual search highlighting; the viewer logs that limitation rather than falling back to whole-document marker insertion. Browser support and whole-viewer performance acceptance remain separate rollout gates. Cached indexing doesn't guarantee responsive capture or rendering for arbitrarily large documents.\n\nUse the existing production-viewer check in `frontend/e2e/markdown-viewer.spec.ts` to attribute performance within the ReactMarkdown path. Its User Timing entries separate preview-search lookup, geometry, scrolling and publication from syntax mapping, geometry, range construction and publication. Geometry reads may force layout; registry calls can include native browser work, but don't necessarily include deferred painting. Worker round trips include transfer and acknowledgements, not just parsing. Source-response, DOM-commit-observer and frame milestones narrow initial-load costs without claiming isolated React CPU or hardware input-to-visible-paint latency. Functional passes don't establish the responsiveness budgets.\n\nInitial-load Markdown normalization uses the shared helper in `frontend/src/utils/markdownCodePreparation.ts`. Documents of at most 4,096 UTF-16 units run the existing canonical normalizer directly, avoiding worker startup and transport for small notes. This bounded path returns the same canonical text and prepared MDAST; it doesn't skip normalization or change rendering. The size limit lives in the shared preparation protocol. Larger documents each own a preparation worker and transfer source, canonical text and an equivalent canonical MDAST in acknowledged, bounded chunks. Tree batches contain at most 512 records and 16,384 string UTF-16 units; individual field pieces are at most 2,048 units. Numeric/flag/position metadata is validated separately, and large text and table alignment fields use the chunk channel instead of content limits. Host acknowledgements yield between tree batches. Success, cancellation, decode failure and timeout terminate the worker; aborted loads can't publish content. Worker failures use the existing load-error path without a synchronous retry, and local preparation failures aren't reported as server overload. The pre-app capability gate requires a callable Web Worker API and otherwise shows the existing unsupported-browser screen without importing the app. The helper retains defensive synchronous normalization with a diagnostic for larger documents when workers are unavailable, but Worker-less app operation isn't supported. API presence doesn't guarantee successful worker construction or execution; existing startup, timeout, crash and decode-error handling remains necessary. The shared protocol is DOM-free. Vite's shared resolver aliases the character decoder to its non-DOM implementation before dependency optimization, so development and production workers use the same implementation. A worker-build-only resolver isn't sufficient for development's prebundled dependencies.\n\nReactMarkdown remains the only application whole-document renderer in every build mode. Its parser hook reuses a defensive clone of the prepared tree only when the tree matches the preview generation's exact source. All normal remark transforms, GFM, table-cell break handling, safe URL/raw HTML behavior and React rendering remain in that path. Cloning prevents those transforms from mutating the retained canonical tree. A successful Save that changes the source releases the superseded tree; edited content without a matching tree uses the normal parser.\n\nRendered Markdown sources of at least 50,000 UTF-16 units use `ProgressiveMarkdown` to append the existing pipeline's fully transformed output. Document-wide references, headings and GFM are resolved once before staging. Chunks aren't parsed as independent Markdown documents. Ordinary sources keep their immediate rendering path. Staged batches use the same ReactMarkdown rendering and safe-link/raw-HTML handling, with at most 1,024 structural nodes or 8,192 text units. Oversized tables, containers and code blocks are subdivided internally, preserving one native table or code block rather than splitting it into separate documents. Already-published nodes aren't replaced by later appends.\n\nThe viewer targets two viewport heights for the initial fill, then yields. Later frames use the 4 ms elapsed-work target without a height limit or repeated per-batch geometry reads. Each frame commits at most four batches, checking elapsed time after every commit to bound work accumulated before native layout. Neither the fill target nor these limits guarantee a maximum task duration: whole-document cloning/transforms, a single commit and native layout remain synchronous. Visible pages use animation frames; hidden pages use timers so completion doesn't wait indefinitely for a frame. Source or rendering-configuration changes and disposal cancel the old publication owner; a restarted generation resets document readiness. A 200 ms delayed, accessible loading indicator disappears immediately on completion and respects reduced motion.\n\nReading published text and closing the viewer remain available during progressive loading. Document search/counts, editing, heading-link navigation and toolbar printing wait for complete publication; syntax painting and DOM search indexing also wait. Browser-menu printing while loading shows a loading notice instead of partial document content. Once complete, normal native selection, search, links and print behavior apply. These controls prevent partial results from being presented as complete; they don't promise that synchronous preparation can never block input.\n\nMarkdown editing reuses the preparation worker for full-document canonical normalization when the editor source contains `\u003cbr`. The existing no-`\u003cbr` typing path still publishes immediately without normalization. If both the original baseline and edited document contain possible table syntax, a background preservation-only job compares their tables without changing that typing normalization policy. Identical sources or documents without a pipe character need no table comparison. Each editor owns at most one active job and one replaceable latest request. Only the current source, baseline, policy and generation can satisfy a prepared snapshot; obsolete success, failure and diagnostic messages are ignored. Worker acknowledgements never replace the native CodeMirror document, recreate table-cell editors or change transaction history. Pending table/IME publication and worker preparation keep the viewer dirty independently of canonical draft publication. External source changes and unmount dispose the old owner and its workers; a baseline change invalidates unmatched prepared bytes.\n\nToolbar Save takes focus before its click handler captures selection. The rich editor therefore remembers the active nested table cell on native focus entry and departure, and refreshes that snapshot when selection is explicitly preserved inside the editor. Stay-edit Save restores the same connected cell within the current root instead of focusing the root and triggering native table-widget reconstruction. If the cell document changed while Save was pending, restoration keeps its newer native selection rather than replaying old offsets. Returning to root-text editing, replacing the external document and unmounting clear the remembered cell; disconnected or replaced cells use the existing root-selection fallback. This doesn't change native transactions, history grouping or composition handling. Production checks require retained cell identity/focus after Save, continued typing, and native undo/redo; these functional checks don't establish responsiveness acceptance.\n\nAsync snapshot capture flushes table/IME publication and worker preparation within the existing transition deadline. It requires full-document normalization even after the typing fast path, so Save retains list, escape and table canonicalization. The same worker performs the unchanged AST-aware table comparison against the exact original baseline, preserving original source for semantically unchanged tables. Source and baseline transfer sequentially in acknowledged chunks of at most 16,384 UTF-16 units, with generation and sequence validation; result chunks retain the same bound. Edit preparation doesn't request a preview tree, whose offsets would no longer match preserved source. Save consumes immutable, complete source-preserving snapshot bytes; repeated serialization returns the captured string without parsing. A successful write acknowledges only its snapshot: newer pending edits stay dirty, and an unavailable newer snapshot doesn't turn the completed write into a failure. Worker failure preserves editing and dirty content; a subsequent explicit async snapshot request can retry, but failures never trigger a synchronous parsing fallback or an automatic retry loop.\n\nSynchronous snapshot capture and canonical getters reject pending or failed worker preparation, including an unmatched source-preservation baseline, rather than returning an older revision as current. Recovery retains its synchronous pagehide/pre-sign-in attempts, debounce and limits; failed capture logs the failure and shows the existing recovery warning. It doesn't mark content saved. Native text sharing is unavailable while publication is pending and reads a complete snapshot when ready. Worker-side normalization and source preservation don't establish whole-viewer timing or resource acceptance; native table editing, layout and preview reconstruction remain separately measured costs.\n\nThe bounded `sambee:edit-preparation:*` entries separate queue wait, worker startup/first acknowledgement, source and baseline transfers, run-to-first-result, result delivery, total transport/job time and complete async snapshot flush. Numeric metadata records generation, source/baseline lengths, policy, chunk counts and whether a completed job is current or obsolete; it contains no source text. Transport completion also reports worker normalization and source-preservation durations separately. Host intervals include event-loop scheduling and acknowledgement delays, so startup isn't isolated worker boot time and transfer isn't pure wire time. Worker durations aren't main-thread CPU, and nested intervals mustn't be added to their enclosing job or snapshot flush. Each stage retains only its latest entry; the existing test observer collects individual samples. Use these measurements to distinguish Save wait from the native table/focus work that can follow write acknowledgement, not to infer a faster Save or passing keyboard/paint budgets from worker offload alone.\n\nThe bounded `sambee:preview-preparation:*` entries separate asynchronous decode elapsed time, load normalization, tree cloning, code-block collection and ReactMarkdown transforms. For worker-backed loads, `load-normalization-elapsed` includes worker startup, transfer, work, host tree assembly, acknowledgements and scheduling, not main-thread CPU time. For small notes, it measures direct canonical normalization and prepared-tree creation. `render-prepared-tree` measures the defensive clone; `render-parse` measures normal parsing when no matching tree is available. The initial-load production matrix requires the clone stage and rejects synchronous `render-parse` and standalone `collection-parse` stages. Live syntax request collection walks the renderer's existing tree; it doesn't parse source again or change markup. The `collection-walk` interval is included in `render-transform`, not additional time to sum. Each generation publishes its ordered requests after DOM commit, before the passive syntax preparation effect, which snapshots them and retains cancellation and stale-generation guards.\n\nThe HAST-ready-to-layout-effect interval includes element construction, reconciliation, commit and scheduling, not just React CPU or paint. Entries contain no source text; each stage retains its latest measurement while the browser test observer collects individual samples. Normalization reuses its parsed tree when canonicalization leaves the source unchanged and reparses in the same preparation path when edits change source offsets. Tree reuse doesn't close responsiveness, retained-memory, syntax-completion or native interaction acceptance.\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Single-Renderer Acceptance\n\nThe retained whole-document viewer integration and its special build-mode selection have been removed. Don't reconnect the historical publisher or add a second renderer to finish shared highlighting. Reuse ReactMarkdown, its parsed-tree code collection, the existing workers and viewport CSS highlights. Standalone renderer proofs are historical research, not application acceptance or a delivery dependency.\n\nRun `npm run build`, then `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production syntax publication' --workers=1 --repeat-each=3` from `frontend/`. The existing matrix uses the approved demo connection and unchanged dense, near-safeguard, host-envelope, many-block and long-line fixtures in Chromium and Firefox at desktop and narrow widths. Add `PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-reactmarkdown-baseline.json` and `--reporter=json` to retain structured reports without npm's console preamble. Each fixture attaches `viewer-timing-budgets.json`, with observed values, numeric targets, pass/fail results and criteria that remain unmeasured.\n\nThe timing gate evaluates file-click-to-text-completion, first exact search, changed query, last-match navigation and maximum viewer timer-service gap. Missing, non-finite or negative samples fail every run; `SAMBEE_E2E_BUDGETS=1` also fails over-budget samples. Omit that flag for functional-only runs, which still attach the budget result. Forced-GC and tracing runs are marked diagnostic and can't enforce timing acceptance. Run `npm run test -- src/utils/__tests__/viewerPerformanceBudgets.test.ts` from `frontend/` for the evaluator's boundary and error tests. These browser-independent checks also run in the normal Vitest CI suite, without repeating them for each browser project. To validate a recorded report, the existing Playwright entry point remains available: `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_REPORT=/tmp/report.json SAMBEE_E2E_SLICE=publication npm run test:e2e -- viewer-performance-budgets.spec.ts --workers=1`.\n\nSearch/query/navigation probes start in browser event handlers, observe the expected count and active highlight in the existing small search controls, and finish after two frames. They avoid page-wide text queries and Playwright round-trip timing, but aren't hardware input-to-visible-paint measurements. The existing active-search fixture deliberately holds syntax preparation; text-load completion doesn't include syntax. Fresh/cached grammar isolation, first usable text/highlight completion, source editing, large prose/tables, resource acceptance and native interaction still require their own evidence. A passing timing subset isn't full rollout acceptance.\n\nThe browser checks compare exact rendered text, native Select All, selected code text and accessibility-tree output. They also exercise keyboard focus, safe links/HTML, GFM tables/tasks, shared Find navigation, theme-variable updates without text-node replacement, native copy events and Chromium PDF generation. These don't establish OS clipboard payloads, browser-native Find reveal, assistive-technology behavior or visual full-document print/PDF correctness. Those remain manual gates.\n\nThe separate native-constraint slice checks representative multiline, long-line and nested Markdown at widths 1543/390 in Chromium/Firefox. It compares cross-block selected text with a trusted keyboard copy/paste payload, exercises keyboard focus and native `window.find` selection/reveal, and attaches real Chromium PDFs. The native text-find API isn't the browser Find toolbar, and a narrow desktop viewport isn't a physical phone. From `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-native-constraints.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production native Markdown constraints' --workers=1 --reporter=json\n```\n\nFrom the repository root, check the attached PDF text with the existing backend environment:\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-native-constraints.json\n```\n\nThe checker rejects missing/duplicate PDF cases, unsuccessful browser results and missing rendered-document lines. Heading IDs use a safe prefix and standard duplicate/Unicode slugging in the existing HAST pipeline; matching fragments are rewritten consistently. Native and printing matrices have independent checks. Chromium's `window.find` reveal is diagnostic-only because it can select without scrolling even outside Sambee; exact selection remains required in both engines, and Firefox reveal remains enforced. Don't add application scrolling to manufacture a native Find pass.\n\nThe Markdown preview's Print icon calls the native browser print dialog; Save as PDF is a destination in that dialog, not a second renderer or server-side conversion. Print isn't offered in edit mode or enabled while loading has failed or is incomplete. Print-only styles hide controls/background UI, release fullscreen/scroll constraints, wrap code/table cells, retain images and use black text on white regardless of the screen theme. Native `beforeprint`/`afterprint` handlers preserve focus, selection and nested scroll, with pending callbacks removed on disposal. The fullscreen paper sizes against its fixed container rather than dynamic viewport units that can retain print-page dimensions.\n\nRun the independent print matrix from `frontend/`, then inspect the PDF attachments from the repository root:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-markdown-printing.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production Markdown printing' --workers=1 --reporter=json\n```\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-markdown-printing.json --printing\n```\n\nThe 24-case matrix covers three fixtures, both themes, both widths and both engines. It verifies action invocation, print CSS, wrapping/widths and actual Chromium PDF state restoration. The PDF gate requires all 12 Chromium outputs to contain every rendered non-whitespace text line and an embedded image. Clear any forced screen-media override before PDF generation; otherwise Playwright prints screen CSS. First/last-page raster inspection supplements text checks. Firefox CSS checks aren't actual Firefox PDF evidence. Actual Firefox PDF and desktop/physical printing were separately confirmed complete by the user on 2026-10-24; no detailed browser/printer support matrix is inferred. Browser destination, paper, margin and header/footer settings remain user-controlled.\n\nKeep performance changes local to measured costs in the current path. Distinguish first visible syntax from completion of all block preparation, and include serialization and parent updates when measuring typing or atomic replace-all. Configuration-only theme and grammar updates must not request caret reveal or replace the document, selection or editor. Don't add streaming, scheduling abstractions or new edit protocols without evidence that the existing path misses its target.\n\nThe existing viewer harness also has a `production source responsiveness` slice for the 54,000-unit dense and 6,000-match long-line source fixtures. It verifies bounded worker delivery, one atomic replacement, undo/redo, exact saved file bytes and worker termination. Save assertions decode the complete multipart body received by the isolated test HTTP proxy; Playwright's request snapshot can omit uploaded file bytes. All traffic uses fixtures, never stored demo edits.\n\nLarge Replace All operations may temporarily block the editor while CodeMirror applies their atomic change set. This latency is an accepted limitation under D5, not permission to truncate output, split history or replace the entire document instead of preserving logical changes. Text and Markdown editors share an editor-owned indeterminate replacement indicator. Worker preparation shows it only after 200 ms; completion before that threshold cancels it without a flash. Ordinary literal replacements stay synchronous and aren't given an artificial delay.\n\nBefore a known-heavy apply, the indicator is shown and given two animation-frame callbacks so the browser has a paint opportunity before the native dispatch. The conservative workload gate requires at least 1,000 replacements and at least 50,000 UTF-16 units in the source or inserted payload. Literal commands inspect at most 1,000 matches for this estimate; worker commands use the completed change plan. This isn't a duration prediction: some fast workloads may be classified as heavy, and unexpectedly slow synchronous work cannot reveal a delayed indicator while blocking the main thread. Feedback already visible during preparation also receives a paint opportunity before application. There's no minimum visible duration or delayed completion, and the spinner doesn't promise continued animation or input responsiveness during synchronous apply.\n\nThe same command boundary covers toolbar and keyboard Replace All. Pending replacements reject duplicate invocations. Any introduced yield revalidates the exact document, query, selection and writability; editing or switching state cancels obsolete work rather than applying stale replacements. Failure, timeout, cancellation and editor disposal release the indicator, animation, timers and listeners. Hidden documents don't wait indefinitely for throttled animation frames. The status uses the editor theme, exposes accessible busy/status semantics and respects reduced motion; physical assistive-technology behavior remains a separate manual check.\n\nThe `production replacement feedback` slice checks quick no-flash behavior and captures visible feedback with the original source still present, then releases held frames and verifies atomic undo/redo, exact multipart Save and editor cleanup in both engines at widths 1543/390. Its held-frame evidence is functional, not timing acceptance.\n\nSource edits retain one bounded User Timing entry per stage: `sambee:source-editor:serialize`, `sambee:source-editor:publish`, `sambee:source-editor:normalize` and `sambee:source-editor:parent-update`. The enclosing publication includes normalization and the synchronous parent callback. These overlapping stages mustn't be added together. Entries contain lengths/revisions, not document contents. `sambee:source-search:commit` brackets the native atomic dispatch, including its synchronous listeners; deferred React work isn't isolated CPU time inside that measure. The separate click-to-completion probe waits for the parent dirty-state render and two subsequent frames. That boundary is a scheduling proxy, not hardware paint.\n\nFrom `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-responsiveness.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nEach sample attaches source-private measurements and explicit 50 ms atomic-dispatch, enclosing serialization/publication and maximum-timer-gap checks. Missing or invalid evidence fails even without `SAMBEE_E2E_BUDGETS`; that flag additionally enforces the original limits. Retain the failed native atomic-application timing results as diagnostic evidence of the D5 accepted limitation, not as passing samples or a reason to repeat performance-only matrices. Unrelated source timing, worker correctness and resource gates remain required. Transfer counts aren't retained/peak memory evidence, and these fixtures don't establish sustained typing, large-table normalization, dense output expansion or scrolling acceptance.\n\nThe separate `production source typing` slice types 82 characters at a requested 10 ms inter-key delay into each 54,000-unit fixture, without per-key polling. It records trusted browser keydown-to-first/two-frame samples, timer gaps, all four edit stages and optional whole-renderer Long Tasks entries, then verifies exact saved source plus the payload. The `source-typing` attachment enforces two-frame p95 strictly below 50 ms and stage/gap maxima at most 50 ms. All 24 engine/width/repeat trials pass; the worst per-trial p95 is 35 ms. This is a scheduling proxy, not physical input-to-painted-pixel acceptance. Unsupported Long Tasks capability stays unmeasured, and observed tasks wouldn't establish application-owned CPU attribution.\n\nThe `production prose table responsiveness` slice mounts the approved 4,000 formatted paragraphs or 2,400 two-column table rows. It checks every rendered paragraph/cell exactly, preserves native block whitespace, root/text-node identity and full rendered text through 60 programmatic scroll steps, and verifies cross-block native selection and close cleanup. Load timing runs from the browser's file-open click through two frames after all expected blocks mount. The `prose-table-responsiveness` attachment separates load budgets, the earlier two-viewport geometry milestone and diagnostic rAF scroll intervals, including the frame following the final scroll assignment. The final 24 trials complete within 1,110 ms, with the first viewport available within 761 ms. Nineteen trials exceed the unchanged 50 ms timer-gap limit, with a worst gap of 128 ms. These recorded loading pauses are accepted under D6, not passing timing samples or isolated CPU attribution. Headless rAF intervals don't establish physical refresh rate, wheel/touch, compositor or painted-frame acceptance. These fixtures have no fenced syntax and don't measure syntax readiness or large-table source normalization.\n\nThe separate `production progressive Markdown loading cancellation` slice holds frame callbacks after two viewport heights exist. It requires visible feedback, disabled document controls, loading-only print output and a working Close action, then releases stale callbacks and verifies complete reopening. It runs in Chromium and Firefox at widths 1543/390. Its paused screenshots and functional passes aren't timing evidence. The existing large-code publication, native interaction and print matrices remain independent regression checks; their completion and acceptance boundaries are recorded below.\n\nRun these slices separately from forced GC and CPU profiling:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-typing.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source typing' --workers=1 --repeat-each=3 --reporter=json\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-prose-table-responsiveness-final.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production prose table responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nFor separate Chromium load attribution, select the same prose/table slice with `SAMBEE_E2E_TRACE=1` and no budget enforcement or forced GC. The `viewer-load-cpu-profile` and `viewer-load-timeline` attachments span file open through completed mounting; nonempty CPU samples and both `sambee:viewer-load:start`/`sambee:viewer-load:complete` timeline markers are required. Budget status is diagnostic, never acceptance. Two desktop captures show one preview build, with a 126.05 ms prose render callback and a 53.69 ms table callback before native style/layout. The prose clone, transforms and HAST-to-layout-effect stages take 38.3, 37.5 and 44.5 ms; these overlap the encompassing callback and mustn't be added to it. Prose native style/layout takes a further 21.14/38.13 ms. Keep cached-tree isolation and native document semantics; neither deleting the clone nor an unapproved publication/renderer change is justified by this evidence. Firefox/mobile CPU attribution remains unverified.\n\nChromium CPU sample deltas can be negative. Reconstruct cumulative sample timestamps, sort them, then clip nonoverlapping intervals to the load markers. Summing only positive deltas inflates CPU weights. Use the marker's renderer PID/thread for main-thread timeline attribution; worker processing and unclassified native samples aren't automatically application-owned blocking CPU.\n\nRepeated source-regex Next/Previous requests are queued in order while navigation is pending. The active navigation worker reuses its transferred document for that burst, applying each native CodeMirror command from the preceding result's selection with the current position's whole-word rules. It terminates when the queue drains; no idle worker is retained. Document/query changes, external selection changes, replacement commands, failures and disposal cancel obsolete queued navigation. Unit tests compare reused-worker navigation with native commands, including mixed directions, wraparound, overlapping matches and zero-length expressions.\n\nThe independent `production source regex parity` slice compares counts and exact saved output with the installed CodeMirror commands for zero-length lookahead, case-sensitive and whole-word matching. A replacement exceeding two source-transfer chunks verifies continuation assembly without truncation. `production source regex lifecycle` injects worker-construction, error/decode-event and startup-timeout failures, requires actionable feedback and a successful retry, and preserves continued editing and exact Save bytes. A partial-delivery case lets one replacement chunk arrive before cancellation, then replays stale change/completion messages; no partial replacement may be committed. These are host-side fault injections, not actual browser-process crash or structured-clone failure evidence. Run both functional slices with:\n\n```sh\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production source regex (parity|lifecycle)' --workers=1\n```\n\nFor optional source renderer footprint diagnostics, use `SAMBEE_E2E_MEMORY=1` without timing enforcement, select `production source responsiveness`, and run the Chromium-only `npm run test:e2e`. The `source-renderer-memory` attachment records CDP renderer heap after explicit GC at pre-open, counted-results, post-replacement and post-close boundaries. Its historical 64 MiB assertion isn't a release criterion under D11. These are whole-viewer post-GC observations, not isolated result-array bytes, peak/worker/native memory or proof of leak-free cleanup. Staged/peak-memory limits and a fixed close/reopen cycle protocol aren't required. The source budget status is diagnostic in memory mode.\n\nFor a separate Chromium CPU diagnostic, use `SAMBEE_E2E_TRACE=1` without `SAMBEE_E2E_BUDGETS=1`, restrict the grep to `production source responsiveness long-line at 1543px`, and run `npm run test:e2e`. The `source-dispatch-cpu-profile` attachment contains the CDP CPU profile; its source budget status is diagnostic, never an acceptance pass. The source slice rejects combined profiling/GC and either diagnostic mode combined with timing enforcement.\n\nFor separate controlled-memory trials, add `SAMBEE_E2E_MEMORY=1` and restrict the existing matrix to the many-block fixture and Chromium. Release harness-held node references before post-GC sampling. Renderer heap excludes worker heaps and aggregate/native memory; a single close isn't repeated-close leak acceptance. Keep forced GC separate from responsiveness timing.\n\nFor diagnostic scheduling traces, add `SAMBEE_E2E_TRACE=1` to a single-fixture Chromium run. The `viewer-scheduling-trace` attachment contains a CDP timeline and V8 CPU profile. Align `sambee:viewer-trace:start` with browser timestamps; join CPU chunks by renderer PID and profile ID and count samples once. Firefox native profiling must use content-process User Timing markers rather than parent-only samples. Profiling adds overhead and isn't acceptance timing.\n\nTo isolate native table input from application work, run the existing proof from `frontend/`:\n\n```sh\nSAMBEE_NATIVE_TABLE_REPORT=/tmp/sambee-native-table node scripts/source-search-containment-proof.mjs --native-table\n```\n\nThis uses public CodeMirror/Lezer and `markdownTables` APIs at the approved demo URL, with an isolated HTML response and default package styling. It edits the middle cell of the fixed 2,400-row table at 1543x900 without React, application CSS, normalization, Save or workers. It requires exact complete native source, atomic full-table replacement spans, native undo/redo and disposal. Native table source uses `\u003cbr\u003e`; application canonicalization to `\u003cbr /\u003e` isn't part of this proof. Root state materialization and view-update intervals are reported separately; input-to-root includes scheduling and deferred publication, not just model CPU. The unminified desktop diagnostic isn't a production acceptance trial or a replacement for mobile, composition and lifecycle checks.\n\nThe optional report prefix writes per-engine JSON and the exact diagnostic bundle. For separate profiling, add `SAMBEE_E2E_TRACE=1` and configure `MOZ_PROFILER_STARTUP=1`, `MOZ_PROFILER_STARTUP_FILTERS=GeckoMain`, `MOZ_PROFILER_STARTUP_FEATURES=js,stackwalk,leaf` and `MOZ_PROFILER_SHUTDOWN` with an absolute output path. Chromium records input-only CPU samples; clip Firefox content-process samples between `sambee:native-table:input-start` and `sambee:native-table:input-end`, excluding construction and history checks. Profiling requires a report prefix and Firefox startup configuration; product-budget enforcement and controlled-GC modes are rejected. Inclusive model, parsing and native reflow samples overlap and mustn't be summed. Unclassified Chromium native samples aren't automatically package JavaScript CPU. Slow native input doesn't by itself establish slow atomic state application or justify private package patches, changed history, wrapping or selection semantics.\n\nCount assertions remain scoped to the existing search controls to avoid page-wide Playwright text caches inside measurement windows. Results are labelled `scoped-controls-v2`; older input figures aren't directly comparable. Handler-to-frame samples and synthetic event age don't establish hardware input-to-visible-paint latency. Removing the alternate renderer doesn't close any performance, memory or manual interaction gate.\n\n### Shared Highlighting Acceptance And Limitations\n\nThe shared-highlighting implementation was approved by the user for merge and rollout on 2026-10-24. Approval doesn't turn failed measurements into passes or establish support for untested devices. Keep original targets, raw verdicts and these scoped acceptance decisions together:\n\n| Decision | Accepted scope | Boundaries |\n|---|---|---|\n| D5 | Noticeable large atomic Replace All latency with visible busy feedback. | Preserve complete output, logical change mapping, one native transaction and undo/redo. Unrelated source-search or typing pauses aren't accepted by this decision. |\n| D6 | The recorded progressive prose/table preview-loading pauses: 19/24 trials above 50 ms, worst 128 ms; all complete within 1,110 ms. | These remain failed gap samples. Longer future delays and other workloads aren't covered. Asynchronous preview preparation remains declined. |\n| D8 | Responsiveness limitations of the existing Markdown table editor. | Table-component timing is diagnostic and non-blocking; exact input, Save, composition, history and cleanup remain required. |\n| D9 | Ten recorded Firefox many-block syntax-color samples at 1,511-1,579 ms against the 1,500 ms target. | All 120 cold/warm samples were collected; 110 meet that target. Full syntax preparation stays within 3,000 ms. No broader delay exception is implied. |\n| D10 | Four recorded Firefox desktop code-display gaps at 51-59 ms against 50 ms. | Preserve the raw failures. Additional delayed-image/font/resize and scroll-anchor test coverage was removed, not passed. Correct content, selection and scrolling remain required. |\n| D11 | Leak investigation and fixes for demonstrated unwanted retention, rather than quantitative memory acceptance. | Staged/peak-memory limits and fixed-cycle shutdown checks were removed, not passed. No exhaustive leak-free claim is made. |\n| D12 | Removal of real-phone and physical keyboard/IME acceptance, including phone print UI and hardware-response measurements. | This isn't verified device support. Automated keyboard/composition, exact editing/Save/recovery and desktop native/print correctness remain required. |\n\nBrowser-menu Find/reveal, OS clipboard, assistive-technology and physical-scrolling checks were confirmed complete by the user on 2026-10-23. Remaining Firefox PDF and desktop/physical printing checks were confirmed complete on 2026-10-24. These are user confirmations, not new automated measurements or a detailed device, browser, AT or printer support matrix. Don't reopen completed checks or rerun accepted timing failures solely to close a checklist; retest affected behavior after a relevant change or demonstrated regression.\n\nThe final editing checks cover theme changes followed by editing exit and Close, late worker results, distinct documents, captured-revision Save with newer dirty edits, failed writes and recovery/snapshot failures. Source-regex terminal cleanup detaches worker handlers, releases terminated workers and clears obsolete replacement buffers, while retaining buffers needed for a pending atomic apply. Ownership review and lifecycle assertions establish the investigated cleanup, not a heap-retention proof for every browser object.\n\nUse `PLAYWRIGHT_JSON_OUTPUT_FILE`, not `PLAYWRIGHT_JSON_OUTPUT_NAME`, for an explicit report path with the JSON reporter. Preserve complete identities, both engines, widths 1543/390, original workloads and three trials per timing identity. Recorded-report evaluation must retain failed samples and reject missing, duplicate, invalid, skipped or retried identities. Functional-only runs and tracing/GC diagnostics don't establish timing passes. Retain local reports before temporary-file cleanup; overlapping runs aren't additive test totals.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. Dedicated formats need a coordinated backend/frontend contract update. Languages already present in the shared CodeMirror catalogue need no separate extension registration for text opening; extra frontend entries are only needed for MIME or presentation metadata.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/fileLanguages.ts` | reuse shared language filename matching; maintain additional plain-text extensions here rather than duplicating language extensions |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare dedicated viewers and optional MIME/presentation metadata; text-viewer assignments are derived automatically |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or the unified `TextEditor`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npm run typecheck\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/settings-form-dialog-pattern", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "settings-form-dialog-pattern", "title": "Settings Form Dialog Pattern", "path": "developer-guide/frontend-architecture/settings-form-dialog-pattern", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 56, "diff_removed": 26}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 64, "diff_removed": 10}}, "content_versions": {"0.9": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveFormDialog` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveFormDialog` as the shared shell for every ordinary application dialog. It provides the responsive Drawer and Dialog behavior, safe-area action area, dialog surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveFormDialog` with the settings form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveFormDialog` with a single-column settings surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveFormDialog` with compact content and actions. Do not add `SettingsFormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveFormDialog` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveFormDialog` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport the structural primitives and control styles from `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `SettingsFormSurface` | Provides the muted, rounded background and shared interior padding. It darkens the default background by 4% in light mode and lightens it by 8% in dark mode. |\n| `SettingsFormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `SettingsFormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `SettingsFormFieldLabel` | Renders a desktop label with its description or validation error. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `settingsFormFieldControlSx` | Aligns a control to the desktop control column. |\n| `settingsFormSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `settingsFormOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `settingsSelectSx` and `settingsSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveFormDialog` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveFormDialog` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `SettingsFormSurface` and one or more `SettingsFormGroup` components.\n3. Put every field in `SettingsFormRow`.\n4. Use `SettingsFormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; reserve helper-text space when a field can show a validation error.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `SettingsFormRow`.\n\nFor a non-form dialog, start with `ResponsiveFormDialog` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Reserve one helper-text line, then replace it with the active error so the form does not shift. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n\n", "1.0": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse translation strings that describe only what the action will do. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n", "2.0": "+++\ntitle = \"Settings Forms and Actions\"\n+++\n\nUse these conventions for settings pages and stateful settings editors. Pages share section, surface, and action styles. Editors keep the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog without separate mobile and desktop forms.\n\nThe page reference is `frontend/src/pages/LocalDrivesSettings.tsx`; the dialog reference is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the page conventions for settings content and actions. Use the dialog pattern when an editor changes several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use the form pattern for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Settings Page Layout and Actions\n\n`SettingsCategoryContent` loads each settings page on demand. Keep page implementations behind its lazy imports rather than importing them into the application shell. Its local loading and error boundaries leave settings navigation available while a page loads or fails. Permission checks run before an admin page renders or its module starts loading. Changing categories must keep navigation focus aligned and prevent a late module from replacing the newly selected page.\n\nOnce the selected page mounts, prefetch the other permitted pages during idle time through the shared `settingsPageLoaders` registry. The mobile category list starts the same prefetch before a page is selected. Deduplicate background loads, log failures without interrupting navigation, and allow failed loads to retry. Cancel scheduled callbacks when the owning view closes or changes. The desktop dialog resets initial focus for each opening and Strict Mode effect replay, keeping the selected category focused without taking focus away from a form or nested dialog during later updates.\n\nCompose settings pages with `SettingsPage`, `SettingsSectionList`, and `SettingsGroup`. Use `FormSurface` for the subdued background of an action section, not an additional bordered card. For action sections, put the description or metadata on the left and controls on the right in a `FormRow`: the columns stack below `md` and share the row at `md` and above. Right-align actions on desktop, allow them to wrap, and keep result notices below the row. An informational section such as Local Drives' Current status can keep its own layout; don't force it into an action row.\n\nThe Local Drives settings-delivery section uses the shared synchronization lifecycle for all authenticated users. Keep its heading, wrap every status in one `FormSurface`, and put section metadata and Refresh or Retry in a `FormRow`. Notices remain below the row. Do not add a manual Apply control, policy approval prompt, administrator-only status read, or nested surface. Show synchronization failure separately from directory-search health.\n\nChoose button styling by the action's role, not by whether its MUI variant is `outlined` or `contained`:\n\n| Role | Treatment | Example |\n|---|---|---|\n| Regular or secondary | Neutral `settingsUtilityButtonSx`; on a grey `FormSurface`, use `settingsFormSurfaceUtilityButtonSx` so the overlay background shows through, as it does for dialog inputs. Keep the existing border, hover, and keyboard-focus treatment. | Account \u003e Change password; Local Drives \u003e Test Current Pairing. |\n| Danger or alert | Red-tinted `settingsDestructiveButtonSx` for settings-page actions. Use the dialog action rules below for the confirmation. | Local Drives \u003e Unpair This Browser. |\n| Main or default | Prominent `settingsPrimaryButtonSx` for the main action on a grey settings-page surface and for the main action in a page footer or dialog. Avoid giving several routine actions the same emphasis. | Authentication \u003e Configure OIDC; Local Drives \u003e Pair This Browser. |\n\nAdd a relevant `@mui/icons-material` icon with `startIcon` to labeled outlined or contained settings-page action buttons that lack one. Leave text-only buttons, including buttons without an explicit outlined or contained variant, without icons. Adding an icon must not change the button's variant, colors, label, or behavior.\n\n## User Directory Layout\n\nUser Management renders roles and statuses as ordinary text, with each simultaneous status on its own line. Summary counts and removable filters remain badges. Keep column headings and cell values readable: wrap headings, email addresses, usernames, provider names, and other long values without truncating their underlying text. Top-align row contents, and reserve space for sort icons and row actions.\n\nUse the settings content container's width to choose between the desktop grid and stacked records, with a shared 40rem breakpoint for the table and its toolbar. Changing selected columns must not change the layout breakpoint. A narrow settings overlay must stack even on a wide screen. Preserve every selected field when stacking; don't introduce horizontal scrolling or silently hide columns. Show timestamps as a short localized date and time on separate lines, retaining the full timestamp in a tooltip and the original value in a semantic `time` element.\n\nPlace the desktop column chooser icon at the far-right end of the table header, above the row actions. In stacked layouts, place the Columns control at the toolbar's right edge. Keep the toolbar control available while the directory is loading or empty. Anchor the menu to the visible control, reposition it when the settings container resizes, and return focus to the visible control when it closes.\n\nValidate the layout in a real browser with all columns enabled, long identifiers, multiple statuses, different regional formats, narrow containers, mobile widths, and zoom. Component tests don't measure text overlap or container-query behavior.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, and Markdown viewers, and the text editor. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\n## Keyboard Isolation\n\n`ResponsiveDialogShell` establishes a keyboard shortcut scope automatically for both its Drawer and Dialog layouts. While it's open, `useKeyboardShortcuts` ignores background registrations and lets the innermost open dialog own shortcuts, including when a control portals outside the dialog. The shell also stops key events from bubbling into parent workspace handlers. Closing the dialog releases its scope; normal shortcut handling resumes when focus returns to the workspace.\n\nDon't add dialog-specific flags to parent shortcut handlers to provide this isolation. Keep ordinary dialog keyboard behavior in the shell's `onKeyDown` or `onEscape` callbacks. If dialog content needs `useKeyboardShortcuts`, register it in a child component rendered inside the shell so it inherits the dialog's scope, not in the component that creates the shell. Existing focus trapping and interactive-control checks still apply.\n\nEscape dismissal goes through MUI's modal close callback, preserving its top-modal and IME process-key checks. `onEscape`, when supplied, replaces the normal Escape close action and runs once, even when `disableClose` blocks ordinary closing. Use it for cancellation requests during pending operations. Close buttons and backdrop requests still use `onClose` and respect `disableClose`. Don't add document-level Escape listeners or duplicate Escape closing in `onKeyDown`; the shared shell owns that behavior.\n\n## Dialog Action Buttons\n\nChoose each action's treatment by what it does, including in decisions embedded inside full-screen viewers. Keep the viewer workspace shell and toolbars separate from its decision dialogs.\n\n| Role | Treatment | Example |\n|---|---|---|\n| Destructive confirmation | MUI `variant=\"contained\" color=\"error\"`, as in the File delete dialog. Do not use the red-tinted settings-page `settingsDestructiveButtonSx` or introduce another red button style. | Delete, Discard unsaved changes, or Continue with overwrite selected. |\n| Main non-destructive action | MUI `variant=\"contained\"` in the theme's primary color. | Create directory, Save, Retry, or the sole Close action. |\n| Secondary or alternate action | MUI `variant=\"outlined\"` with the existing subdued utility fill and focus treatment. | Cancel, Later, Ignore, or Open without saving. |\n\nAn action's role can change with the selected option: a conflict dialog's Continue is destructive only when it will overwrite an existing item. When a decision offers both Save and Discard, distinguish the primary and destructive actions without changing what either one does. Do not restyle settings-page triggers when styling their confirmation dialogs.\n\nVisual priority does not determine Enter behavior. For safety-critical decisions, focus the least destructive action on opening; for input workflows, focus the first input. Never make a destructive action the default Enter action unless the user has already focused it. Keep cancellation available and focused during cancellable pending operations. Use `ResponsiveDialogShell` for application confirmations rather than native `window.confirm`, whose buttons cannot follow these styles.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- For text inputs and selects with an external label in the left column, use MUI `size=\"small\"` and omit the control's `label` or `InputLabel`. The left-column label is the only visible label; associate it with the control so it remains accessible. Below `md`, restore the control's floating label and normal height.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse translation strings that describe only what the action will do. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor settings-page action sections, check the one-column layout below `md` and the two-column description/action layout at `md` and above. Check neutral-button contrast against grey form surfaces in light and dark themes, including hover and keyboard focus. Check that added icons do not change accessible names or cause button labels to overflow at phone widths. Keep informational sections readable without imposing the action-row grid, and verify that notices remain below the row.\n\nFor dialog actions, check contained error and primary buttons and outlined secondary buttons in light and dark themes, including hover and keyboard focus. Verify that option-dependent destructive actions change treatment without changing their safe initial focus or Enter behavior.\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveFormDialog` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveFormDialog` as the shared shell for every ordinary application dialog. It provides the responsive Drawer and Dialog behavior, safe-area action area, dialog surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveFormDialog` with the settings form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveFormDialog` with a single-column settings surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveFormDialog` with compact content and actions. Do not add `SettingsFormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveFormDialog` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveFormDialog` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport the structural primitives and control styles from `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `SettingsFormSurface` | Provides the muted, rounded background and shared interior padding. It darkens the default background by 4% in light mode and lightens it by 8% in dark mode. |\n| `SettingsFormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `SettingsFormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `SettingsFormFieldLabel` | Renders a desktop label with its description or validation error. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `settingsFormFieldControlSx` | Aligns a control to the desktop control column. |\n| `settingsFormSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `settingsFormOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `settingsSelectSx` and `settingsSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveFormDialog` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveFormDialog` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `SettingsFormSurface` and one or more `SettingsFormGroup` components.\n3. Put every field in `SettingsFormRow`.\n4. Use `SettingsFormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; reserve helper-text space when a field can show a validation error.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `SettingsFormRow`.\n\nFor a non-form dialog, start with `ResponsiveFormDialog` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Reserve one helper-text line, then replace it with the active error so the form does not shift. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n\n", "1.0": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse translation strings that describe only what the action will do. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n", "2.0": "+++\ntitle = \"Settings Forms and Actions\"\n+++\n\nUse these conventions for settings pages and stateful settings editors. Pages share section, surface, and action styles. Editors keep the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog without separate mobile and desktop forms.\n\nThe page reference is `frontend/src/pages/LocalDrivesSettings.tsx`; the dialog reference is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the page conventions for settings content and actions. Use the dialog pattern when an editor changes several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use the form pattern for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Settings Page Layout and Actions\n\n`SettingsCategoryContent` loads each settings page on demand. Keep page implementations behind its lazy imports rather than importing them into the application shell. Its local loading and error boundaries leave settings navigation available while a page loads or fails. Permission checks run before an admin page renders or its module starts loading. Changing categories must keep navigation focus aligned and prevent a late module from replacing the newly selected page.\n\nOnce the selected page mounts, prefetch the other permitted pages during idle time through the shared `settingsPageLoaders` registry. The mobile category list starts the same prefetch before a page is selected. Deduplicate background loads, log failures without interrupting navigation, and allow failed loads to retry. Cancel scheduled callbacks when the owning view closes or changes. The desktop dialog resets initial focus for each opening and Strict Mode effect replay, keeping the selected category focused without taking focus away from a form or nested dialog during later updates.\n\nCompose settings pages with `SettingsPage`, `SettingsSectionList`, and `SettingsGroup`. Use `FormSurface` for the subdued background of an action section, not an additional bordered card. For action sections, put the description or metadata on the left and controls on the right in a `FormRow`: the columns stack below `md` and share the row at `md` and above. Right-align actions on desktop, allow them to wrap, and keep result notices below the row. An informational section such as Local Drives' Current status can keep its own layout; don't force it into an action row.\n\nThe Local Drives settings-delivery section uses the shared synchronization lifecycle for all authenticated users. Keep its heading, wrap every status in one `FormSurface`, and put section metadata and Refresh or Retry in a `FormRow`. Notices remain below the row. Do not add a manual Apply control, policy approval prompt, administrator-only status read, or nested surface. Show synchronization failure separately from directory-search health.\n\nChoose button styling by the action's role, not by whether its MUI variant is `outlined` or `contained`:\n\n| Role | Treatment | Example |\n|---|---|---|\n| Regular or secondary | Neutral `settingsUtilityButtonSx`; on a grey `FormSurface`, use `settingsFormSurfaceUtilityButtonSx` so the overlay background shows through, as it does for dialog inputs. Keep the existing border, hover, and keyboard-focus treatment. | Account \u003e Change password; Local Drives \u003e Test Current Pairing. |\n| Danger or alert | Red-tinted `settingsDestructiveButtonSx` for settings-page actions. Use the dialog action rules below for the confirmation. | Local Drives \u003e Unpair This Browser. |\n| Main or default | Prominent `settingsPrimaryButtonSx` for the main action on a grey settings-page surface and for the main action in a page footer or dialog. Avoid giving several routine actions the same emphasis. | Authentication \u003e Configure OIDC; Local Drives \u003e Pair This Browser. |\n\nAdd a relevant `@mui/icons-material` icon with `startIcon` to labeled outlined or contained settings-page action buttons that lack one. Leave text-only buttons, including buttons without an explicit outlined or contained variant, without icons. Adding an icon must not change the button's variant, colors, label, or behavior.\n\n## User Directory Layout\n\nUser Management renders roles and statuses as ordinary text, with each simultaneous status on its own line. Summary counts and removable filters remain badges. Keep column headings and cell values readable: wrap headings, email addresses, usernames, provider names, and other long values without truncating their underlying text. Top-align row contents, and reserve space for sort icons and row actions.\n\nUse the settings content container's width to choose between the desktop grid and stacked records, with a shared 40rem breakpoint for the table and its toolbar. Changing selected columns must not change the layout breakpoint. A narrow settings overlay must stack even on a wide screen. Preserve every selected field when stacking; don't introduce horizontal scrolling or silently hide columns. Show timestamps as a short localized date and time on separate lines, retaining the full timestamp in a tooltip and the original value in a semantic `time` element.\n\nPlace the desktop column chooser icon at the far-right end of the table header, above the row actions. In stacked layouts, place the Columns control at the toolbar's right edge. Keep the toolbar control available while the directory is loading or empty. Anchor the menu to the visible control, reposition it when the settings container resizes, and return focus to the visible control when it closes.\n\nValidate the layout in a real browser with all columns enabled, long identifiers, multiple statuses, different regional formats, narrow containers, mobile widths, and zoom. Component tests don't measure text overlap or container-query behavior.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, and Markdown viewers, and the text editor. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\n## Keyboard Isolation\n\n`ResponsiveDialogShell` establishes a keyboard shortcut scope automatically for both its Drawer and Dialog layouts. While it's open, `useKeyboardShortcuts` ignores background registrations and lets the innermost open dialog own shortcuts, including when a control portals outside the dialog. The shell also stops key events from bubbling into parent workspace handlers. Closing the dialog releases its scope; normal shortcut handling resumes when focus returns to the workspace.\n\nDon't add dialog-specific flags to parent shortcut handlers to provide this isolation. Keep ordinary dialog keyboard behavior in the shell's `onKeyDown` or `onEscape` callbacks. If dialog content needs `useKeyboardShortcuts`, register it in a child component rendered inside the shell so it inherits the dialog's scope, not in the component that creates the shell. Existing focus trapping and interactive-control checks still apply.\n\nEscape dismissal goes through MUI's modal close callback, preserving its top-modal and IME process-key checks. `onEscape`, when supplied, replaces the normal Escape close action and runs once, even when `disableClose` blocks ordinary closing. Use it for cancellation requests during pending operations. Close buttons and backdrop requests still use `onClose` and respect `disableClose`. Don't add document-level Escape listeners or duplicate Escape closing in `onKeyDown`; the shared shell owns that behavior.\n\n## Dialog Action Buttons\n\nChoose each action's treatment by what it does, including in decisions embedded inside full-screen viewers. Keep the viewer workspace shell and toolbars separate from its decision dialogs.\n\n| Role | Treatment | Example |\n|---|---|---|\n| Destructive confirmation | MUI `variant=\"contained\" color=\"error\"`, as in the File delete dialog. Do not use the red-tinted settings-page `settingsDestructiveButtonSx` or introduce another red button style. | Delete, Discard unsaved changes, or Continue with overwrite selected. |\n| Main non-destructive action | MUI `variant=\"contained\"` in the theme's primary color. | Create directory, Save, Retry, or the sole Close action. |\n| Secondary or alternate action | MUI `variant=\"outlined\"` with the existing subdued utility fill and focus treatment. | Cancel, Later, Ignore, or Open without saving. |\n\nAn action's role can change with the selected option: a conflict dialog's Continue is destructive only when it will overwrite an existing item. When a decision offers both Save and Discard, distinguish the primary and destructive actions without changing what either one does. Do not restyle settings-page triggers when styling their confirmation dialogs.\n\nVisual priority does not determine Enter behavior. For safety-critical decisions, focus the least destructive action on opening; for input workflows, focus the first input. Never make a destructive action the default Enter action unless the user has already focused it. Keep cancellation available and focused during cancellable pending operations. Use `ResponsiveDialogShell` for application confirmations rather than native `window.confirm`, whose buttons cannot follow these styles.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- For text inputs and selects with an external label in the left column, use MUI `size=\"small\"` and omit the control's `label` or `InputLabel`. The left-column label is the only visible label; associate it with the control so it remains accessible. Below `md`, restore the control's floating label and normal height.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nDescribe what the selected action will do. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse translation strings that describe only what the action will do. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor settings-page action sections, check the one-column layout below `md` and the two-column description/action layout at `md` and above. Check neutral-button contrast against grey form surfaces in light and dark themes, including hover and keyboard focus. Check that added icons do not change accessible names or cause button labels to overflow at phone widths. Keep informational sections readable without imposing the action-row grid, and verify that notices remain below the row.\n\nFor dialog actions, check contained error and primary buttons and outlined secondary buttons in light and dark themes, including hover and keyboard focus. Verify that option-dependent destructive actions change treatment without changing their safe initial focus or Enter behavior.\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/companion-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "companion-architecture", "title": "Companion Architecture", "path": "developer-guide/companion-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "0.8": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "0.9": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "1.0": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "2.0": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/companion-overview", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "companion-overview", "title": "Companion Overview", "path": "developer-guide/companion-architecture/companion-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/companion-runtime-and-native-app-editing", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "companion-runtime-and-native-app-editing", "title": "Companion Runtime And Native App Editing", "path": "developer-guide/companion-architecture/companion-runtime-and-native-app-editing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/browser-to-companion-trust-model", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "browser-to-companion-trust-model", "title": "Browser To Companion Trust Model", "path": "developer-guide/companion-architecture/browser-to-companion-trust-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 8}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 23, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a companion bootstrap token.\n1. Companion uses that bootstrap token to look up file info, acquire the edit lock, receive an operation-scoped token plus lock context, and later upload or release through that narrower edit-session authority.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\nAfter lock acquisition, the browser no longer carries the authority for that edit. The companion holds an operation-scoped backend token plus `operation_id`, `lock_id`, and `lock_capability` for the lifetime of the edit session.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing.\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace explicit pairing with silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, bootstrap tokens, operation tokens, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.8": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.9": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "1.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "2.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Shared Settings Delivery\n\nSuccessful pairing selects the authoritative server for theme, localization, and directory-index resource policy. Pairing again selects that origin again. Failed or cancelled pairing, authenticated status requests, reconnects, and background checks must not change authority. Both native and HTTP unpair paths use `PairingState`; removing the authoritative origin clears authority without selecting a replacement or resetting valid settings.\n\nThe version-1 protocol uses typed `theme`, `localization`, and `directory_index` sections. Theme contains only `id`, `mode`, and `primary.main`. Localization contains stored language and regional-locale preferences, including `browser`. The Companion resolves `browser` from its operating-system webview locale. Directory policy retains its server revision; user sections use SHA-256 digests of canonical payloads and include a user scope.\n\n| Endpoint | Responsibility |\n|---|---|\n| `GET /api/admin/settings/companion` | Authenticated metadata and section markers; not restricted to administrators |\n| `POST /api/admin/settings/companion/grants` | Issue a short-lived, single-use grant for selected sections |\n| `POST /api/admin/settings/companion/grants/redeem` | Direct Companion retrieval of canonical server sections |\n| Companion `GET /api/settings` | Authority and per-section status |\n| Companion `POST /api/settings/challenge` | Authenticated challenge; no extra approval prompt |\n| Companion `POST /api/settings/redeem` | Serialized retrieval and application through the paired authority |\n\nThe browser sends an opaque grant to Companion, not settings payloads. Grants bind origin, Companion ID, challenge, backend identity, user credentials, selected markers, and user-switch permission. Redemption rechecks active user status, credential version, and any issuing OIDC session, then rebuilds selected sections. Changed settings require a fresh grant. Capacity is limited globally and per user. Editing directory policy remains administrator-only.\n\n`CompanionSettingsSync` owns browser synchronization independently of Settings visibility or role. It checks metadata every 30 seconds while visible, compares native markers, and requests a grant only for changed sections. Web Locks serialize work across tabs. Native serialization and marker comparisons make repeated delivery a no-op. Logout and disposal stop work; identity changes cancel stale responses. Pairing, login, and explicit preference changes can change user scope. Background checks and reconnects cannot switch the applied user.\n\nCompanion rechecks authority under its authority lock before committing settings. Directory revisions are ordered only within an origin and backend identity; a new authority or backend identity can start at a lower revision. Supplied sections are validated before application. Per-section failures preserve last valid values and must not report synchronization success. Settings failure is distinct from directory search or index health.\n\nExisting pairings, indexes, and valid policy are retained. Migration selects a still-paired legacy policy binding, or a single legacy pairing. Several unordered legacy pairings require pairing the intended server again. Authority is persisted in the keychain. Old delivery endpoints return an update-required response, not manual policy approval. URI theme delivery is bootstrap-only and cannot override managed settings, including after unpairing.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a companion bootstrap token.\n1. Companion uses that bootstrap token to look up file info, acquire the edit lock, receive an operation-scoped token plus lock context, and later upload or release through that narrower edit-session authority.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\nAfter lock acquisition, the browser no longer carries the authority for that edit. The companion holds an operation-scoped backend token plus `operation_id`, `lock_id`, and `lock_capability` for the lifetime of the edit session.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing.\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace explicit pairing with silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, bootstrap tokens, operation tokens, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.8": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.9": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "1.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "2.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Shared Settings Delivery\n\nSuccessful pairing selects the authoritative server for theme, localization, and directory-index resource policy. Pairing again selects that origin again. Failed or cancelled pairing, authenticated status requests, reconnects, and background checks must not change authority. Both native and HTTP unpair paths use `PairingState`; removing the authoritative origin clears authority without selecting a replacement or resetting valid settings.\n\nThe version-1 protocol uses typed `theme`, `localization`, and `directory_index` sections. Theme contains only `id`, `mode`, and `primary.main`. Localization contains stored language and regional-locale preferences, including `browser`. The Companion resolves `browser` from its operating-system webview locale. Directory policy retains its server revision; user sections use SHA-256 digests of canonical payloads and include a user scope.\n\n| Endpoint | Responsibility |\n|---|---|\n| `GET /api/admin/settings/companion` | Authenticated metadata and section markers; not restricted to administrators |\n| `POST /api/admin/settings/companion/grants` | Issue a short-lived, single-use grant for selected sections |\n| `POST /api/admin/settings/companion/grants/redeem` | Direct Companion retrieval of canonical server sections |\n| Companion `GET /api/settings` | Authority and per-section status |\n| Companion `POST /api/settings/challenge` | Authenticated challenge; no extra approval prompt |\n| Companion `POST /api/settings/redeem` | Serialized retrieval and application through the paired authority |\n\nThe browser sends an opaque grant to Companion, not settings payloads. Grants bind origin, Companion ID, challenge, backend identity, user credentials, selected markers, and user-switch permission. Redemption rechecks active user status, credential version, and any issuing OIDC session, then rebuilds selected sections. Changed settings require a fresh grant. Capacity is limited globally and per user. Editing directory policy remains administrator-only.\n\n`CompanionSettingsSync` owns browser synchronization independently of Settings visibility or role. It checks metadata every 30 seconds while visible, compares native markers, and requests a grant only for changed sections. Web Locks serialize work across tabs. Native serialization and marker comparisons make repeated delivery a no-op. Logout and disposal stop work; identity changes cancel stale responses. Pairing, login, and explicit preference changes can change user scope. Background checks and reconnects cannot switch the applied user.\n\nCompanion rechecks authority under its authority lock before committing settings. Directory revisions are ordered only within an origin and backend identity; a new authority or backend identity can start at a lower revision. Supplied sections are validated before application. Per-section failures preserve last valid values and must not report synchronization success. Settings failure is distinct from directory search or index health.\n\nExisting pairings, indexes, and valid policy are retained. Migration selects a still-paired legacy policy binding, or a single legacy pairing. Several unordered legacy pairings require pairing the intended server again. Authority is persisted in the keychain. Old delivery endpoints return an update-required response, not manual policy approval. URI theme delivery is bootstrap-only and cannot override managed settings, including after unpairing.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/local-drive-and-save-back-pipeline", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "local-drive-and-save-back-pipeline", "title": "Local Drive And Save Back Pipeline", "path": "developer-guide/companion-architecture/local-drive-and-save-back-pipeline", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 16, "diff_removed": 6}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 25, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability and pairing state\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for a bootstrap token\n3. it fetches metadata and conflict baseline information\n4. it acquires the backend edit lock and receives operation-scoped lock context\n5. it downloads the file to a temp directory\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while renewal, heartbeat, and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.8": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.9": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "1.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "2.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nLocalhost bootstrap follows these rules:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Directory-Index Policy Delivery\n\nDirectory policy uses the shared settings protocol described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/#shared-settings-delivery). Pairing selects authority and permits automatic delivery by any active, authenticated user. Only administrators can edit policy. Companion retrieves canonical settings directly from the authoritative backend without redirects.\n\nUpdates serialize against source initialization. Unchanged revisions are no-ops within the same backend identity. Failed delivery or persistence preserves the last valid policy. Authority changes invalidate pending delivery. File APIs must protect policy and index storage from modification. Policy synchronization state is separate from index health.\n\nLocal-drive scans keep committed rows and queued work after interruption or reopen. Child FileIds commit with parent groups and are checked before child traversal. A changed identity requires a fresh parent listing before its children can enter the index. Status polls use memory snapshots; real queries reuse read-only SQLite connections with file-binding checks. Active work prevents idle release, and the shared browser status shows live scan counts.\n\nLinux uses `openat2` when available and no-follow statx checks for directory children. Only ENOSYS disables future `openat2` attempts; permission, link, and mount errors stay errors. The fallback checks each ancestor without following links. Regular files with known entry types need no metadata call; DT_UNKNOWN entries use no-follow metadata before directory checks. Windows uses the shared 1 MiB enumeration buffer. It validates names, attributes, and reparse tags from directory records and preserves full 128-bit FileIds without opening each child. The queued FileId is checked before that child is traversed.\n\nWindows full scans use `OpenFileById` for parents with queued identities. The returned full identity, volume, directory attributes, and exact native path must match. A 64-bit descriptor is used only when it preserves the full stored identity. If FileId opens cannot supply the parent, relative `NtCreateFile` opens it from the retained root. Relative names are validated before I/O; intermediate and final reparse points are rejected. The returned directory must match the root volume and exact native path. The manager defers a replacement identity before its children can be published. Definite unsupported modes are cached per root, with the checked ancestor walk as the final fallback. Permission, redirection, and transport failures remain errors.\n\nEach native scan retains its checked parent descriptor or ancestor chain through enumeration, batch validation, and pruning. With a healthy watcher, commit and child checks use that read without reopening the parent path. On Linux, a missing, failed, or not-yet-ready watcher requires a root-relative parent identity check before each child batch and final parent completion. This check also applies to parallel full-pass and reconciliation reads. Queued identity and observation-token checks still guard writes.\n\nFull passes verify the root when binding and before acceptance. Between these probes, parent reads check the held root locally. Read errors and traversal issues request another full probe before the next parent opens. Version counters preserve requests raised during a probe. Standalone reads and reconciliation keep full root checks. Windows standalone and final ancestor-walk fallback reads retain no-delete ancestor chains; FileId and relative reads retain the parent handle. Held-parent identity and native-path checks run at read boundaries rather than for each record. Non-root full-pass handles permit delete sharing; the root and strict standalone handles retain no-delete sharing.\n\nFull scans and reconciliation read independent parents with at most four worker threads through a bounded channel. Only the scan thread writes. Paged queue reads carry FileIds; ancestor groups commit before descendants start. Both modes use adaptive content/bookkeeping groups and one disk reservation per group. Reconciliation retains strict reads and does not advance the full-verification clock. Item issue counts stay with observation tokens until final snapshot commit; stale tokens discard their counts and leave work pending. Group exit releases buffered ownership, including after an interruption or storage error.\n\nSee [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for shared index rules and [Manage Directory Search](../../../admin-guide/operations-and-maintenance/manage-directory-search/) for the administrator workflow.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nNative watchers do not report deletion of the watched directory on every platform. The companion also checks the target once per second. If the directory is missing or is no longer a directory, the companion removes its watcher state before it sends the change notification. A later subscription can watch a recreated directory.\n\nDirectory requests distinguish a missing path from a path with a file in place of a parent directory. This distinction also applies on Windows, where both cases can produce a missing-path OS error. Only a confirmed missing directory returns `directory_not_found`; a file used as a parent returns `not_a_directory`.\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability and pairing state\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for a bootstrap token\n3. it fetches metadata and conflict baseline information\n4. it acquires the backend edit lock and receives operation-scoped lock context\n5. it downloads the file to a temp directory\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while renewal, heartbeat, and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.8": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.9": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "1.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "2.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nLocalhost bootstrap follows these rules:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Directory-Index Policy Delivery\n\nDirectory policy uses the shared settings protocol described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/#shared-settings-delivery). Pairing selects authority and permits automatic delivery by any active, authenticated user. Only administrators can edit policy. Companion retrieves canonical settings directly from the authoritative backend without redirects.\n\nUpdates serialize against source initialization. Unchanged revisions are no-ops within the same backend identity. Failed delivery or persistence preserves the last valid policy. Authority changes invalidate pending delivery. File APIs must protect policy and index storage from modification. Policy synchronization state is separate from index health.\n\nLocal-drive scans keep committed rows and queued work after interruption or reopen. Child FileIds commit with parent groups and are checked before child traversal. A changed identity requires a fresh parent listing before its children can enter the index. Status polls use memory snapshots; real queries reuse read-only SQLite connections with file-binding checks. Active work prevents idle release, and the shared browser status shows live scan counts.\n\nLinux uses `openat2` when available and no-follow statx checks for directory children. Only ENOSYS disables future `openat2` attempts; permission, link, and mount errors stay errors. The fallback checks each ancestor without following links. Regular files with known entry types need no metadata call; DT_UNKNOWN entries use no-follow metadata before directory checks. Windows uses the shared 1 MiB enumeration buffer. It validates names, attributes, and reparse tags from directory records and preserves full 128-bit FileIds without opening each child. The queued FileId is checked before that child is traversed.\n\nWindows full scans use `OpenFileById` for parents with queued identities. The returned full identity, volume, directory attributes, and exact native path must match. A 64-bit descriptor is used only when it preserves the full stored identity. If FileId opens cannot supply the parent, relative `NtCreateFile` opens it from the retained root. Relative names are validated before I/O; intermediate and final reparse points are rejected. The returned directory must match the root volume and exact native path. The manager defers a replacement identity before its children can be published. Definite unsupported modes are cached per root, with the checked ancestor walk as the final fallback. Permission, redirection, and transport failures remain errors.\n\nEach native scan retains its checked parent descriptor or ancestor chain through enumeration, batch validation, and pruning. With a healthy watcher, commit and child checks use that read without reopening the parent path. On Linux, a missing, failed, or not-yet-ready watcher requires a root-relative parent identity check before each child batch and final parent completion. This check also applies to parallel full-pass and reconciliation reads. Queued identity and observation-token checks still guard writes.\n\nFull passes verify the root when binding and before acceptance. Between these probes, parent reads check the held root locally. Read errors and traversal issues request another full probe before the next parent opens. Version counters preserve requests raised during a probe. Standalone reads and reconciliation keep full root checks. Windows standalone and final ancestor-walk fallback reads retain no-delete ancestor chains; FileId and relative reads retain the parent handle. Held-parent identity and native-path checks run at read boundaries rather than for each record. Non-root full-pass handles permit delete sharing; the root and strict standalone handles retain no-delete sharing.\n\nFull scans and reconciliation read independent parents with at most four worker threads through a bounded channel. Only the scan thread writes. Paged queue reads carry FileIds; ancestor groups commit before descendants start. Both modes use adaptive content/bookkeeping groups and one disk reservation per group. Reconciliation retains strict reads and does not advance the full-verification clock. Item issue counts stay with observation tokens until final snapshot commit; stale tokens discard their counts and leave work pending. Group exit releases buffered ownership, including after an interruption or storage error.\n\nSee [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for shared index rules and [Manage Directory Search](../../../admin-guide/operations-and-maintenance/manage-directory-search/) for the administrator workflow.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nNative watchers do not report deletion of the watched directory on every platform. The companion also checks the target once per second. If the directory is missing or is no longer a directory, the companion removes its watcher state before it sends the change notification. A later subscription can watch a recreated directory.\n\nDirectory requests distinguish a missing path from a path with a file in place of a parent directory. This distinction also applies on Windows, where both cases can produce a missing-path OS error. Only a confirmed missing directory returns `directory_not_found`; a file used as a parent returns `not_a_directory`.\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/cross-cutting-systems", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "cross-cutting-systems", "title": "Cross-Cutting Systems", "path": "developer-guide/cross-cutting-systems", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "0.8": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "0.9": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "1.0": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "2.0": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/logging-and-localization", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "logging-and-localization", "title": "Logging And Localization", "path": "developer-guide/cross-cutting-systems/logging-and-localization", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 43, "diff_removed": 22}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 16, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.8": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.9": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "1.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "2.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n### Directory-Search Diagnostics\n\nUse fixed event names and route templates with status, duration, and counts. Do not log search terms, request payloads, pairing codes, or credentials. Omit paths except for the bounded directory-scan item diagnostics below. Log committed changes only after commit; use numeric error codes instead of exception text that can expose private data.\n\nDirectory scans emit `directory_scan_started`, `directory_scan_finished`, and `directory_scan_invalidated` at INFO. Finish events report committed progress, group commits, duration, and a fixed abort reason. Invalidation events include the reason and a counter, even when the reason repeats. Use these events to distinguish a resumed pass from repeated observation loss. A lifecycle change alone does not require completed parents to be read again.\n\nItem diagnostics use the fixed codes `access_denied`, `unsafe_traversal`, `unsupported_encoding`, and `scan_failed`. The shared `max_logged_scan_issues_per_pass` limit permits at most 20 individual INFO messages in total per pass, with a quoted source path and no private exception text. Restrict access to logs because these messages contain directory names. Pass totals retain all issue counts, including suppressed messages. Backend finish events carry numeric totals; Companion emits `directory_scan_issue_totals` before its finish event. Partial coverage is not a scan abort.\n\nBackend pass logs include `smb_round_trips`, the number of directory-index request groups attempted during the pass. One compound counts once, not once for each message. Root and metadata probes, loop queries, cleanup requests, and credit-growth echoes count separately. Credit admission that rejects a compound without sending it counts zero. Failed send attempts count, so this is not a measurement of completed network exchanges or latency. Ordinary file browsing is not included.\n\nCompanion pass logs include `native_opens`, the number of directory-open attempts made by the source traversal during the pass. The count includes root verification, Linux mount-policy directory checks, fallback traversal, and failed opens. It excludes metadata queries, closes, and index-file I/O. Both counters use per-pass differences from a source-owned total, which survives root rebinding. Start events include the prepared generation, phase, queue counts, and I/O performed during setup. Use the counters to identify repeated opens and probes, and the duration to measure elapsed scan time.\n\nSee [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for lifecycle and storage rules. See [Companion Support Reference](../../../admin-guide/reference/companion-support-reference/#logging-controls) for operational logging controls.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Companion localization uses the shared settings protocol. Deliver stored preferences, including `browser`; Companion resolves them from its own operating-system locale.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser UI formatting uses effective locale values. Shared Companion delivery carries stored preferences, and Companion resolves its own effective locale.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.8": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.9": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "1.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "2.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n### Directory-Search Diagnostics\n\nUse fixed event names and route templates with status, duration, and counts. Do not log search terms, request payloads, pairing codes, or credentials. Omit paths except for the bounded directory-scan item diagnostics below. Log committed changes only after commit; use numeric error codes instead of exception text that can expose private data.\n\nDirectory scans emit `directory_scan_started`, `directory_scan_finished`, and `directory_scan_invalidated` at INFO. Finish events report committed progress, group commits, duration, and a fixed abort reason. Invalidation events include the reason and a counter, even when the reason repeats. Use these events to distinguish a resumed pass from repeated observation loss. A lifecycle change alone does not require completed parents to be read again.\n\nItem diagnostics use the fixed codes `access_denied`, `unsafe_traversal`, `unsupported_encoding`, and `scan_failed`. The shared `max_logged_scan_issues_per_pass` limit permits at most 20 individual INFO messages in total per pass, with a quoted source path and no private exception text. Restrict access to logs because these messages contain directory names. Pass totals retain all issue counts, including suppressed messages. Backend finish events carry numeric totals; Companion emits `directory_scan_issue_totals` before its finish event. Partial coverage is not a scan abort.\n\nBackend pass logs include `smb_round_trips`, the number of directory-index request groups attempted during the pass. One compound counts once, not once for each message. Root and metadata probes, loop queries, cleanup requests, and credit-growth echoes count separately. Credit admission that rejects a compound without sending it counts zero. Failed send attempts count, so this is not a measurement of completed network exchanges or latency. Ordinary file browsing is not included.\n\nCompanion pass logs include `native_opens`, the number of directory-open attempts made by the source traversal during the pass. The count includes root verification, Linux mount-policy directory checks, fallback traversal, and failed opens. It excludes metadata queries, closes, and index-file I/O. Both counters use per-pass differences from a source-owned total, which survives root rebinding. Start events include the prepared generation, phase, queue counts, and I/O performed during setup. Use the counters to identify repeated opens and probes, and the duration to measure elapsed scan time.\n\nSee [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for lifecycle and storage rules. See [Companion Support Reference](../../../admin-guide/reference/companion-support-reference/#logging-controls) for operational logging controls.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Companion localization uses the shared settings protocol. Deliver stored preferences, including `browser`; Companion resolves them from its own operating-system locale.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser UI formatting uses effective locale values. Shared Companion delivery carries stored preferences, and Companion resolves its own effective locale.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/localization-and-locale-behavior", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "localization-and-locale-behavior", "title": "Localization And Locale Behavior", "path": "developer-guide/cross-cutting-systems/localization-and-locale-behavior", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 10, "diff_removed": 8}}, "content_versions": {"0.7": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.8": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.9": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "1.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "2.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nLocalization uses [Shared Settings Delivery](../../companion-architecture/browser-to-companion-trust-model/#shared-settings-delivery) with theme and directory policy. Pairing selects the authoritative server. The backend builds localization from the authenticated user's stored preferences; the browser delivers only a grant.\n\nImportant rules:\n\n- Delivery preserves `browser`. Companion resolves it from its operating-system webview locale, not from the remote browser.\n- Localization has its own canonical payload digest and user scope. An unchanged section is not written again.\n- Pairing, login, and an explicit persisted preference change can change the active user. Periodic checks and reconnects cannot switch users.\n- Rust persists localization atomically, and native windows mirror effective values into local storage for fast startup.\n- Open windows receive localization update events. A new window reads the current native state.\n- The stored update timestamp is diagnostic data, not an ordering credential.\n- A failed section keeps its last valid values and reports delivery failure independently of directory search.\n\nThe separate localhost localization endpoint is retired. Incompatible clients must update; do not restore a parallel synchronizer.\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n"}, "page_contents": {"0.7": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.8": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.9": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "1.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "2.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nLocalization uses [Shared Settings Delivery](../../companion-architecture/browser-to-companion-trust-model/#shared-settings-delivery) with theme and directory policy. Pairing selects the authoritative server. The backend builds localization from the authenticated user's stored preferences; the browser delivers only a grant.\n\nImportant rules:\n\n- Delivery preserves `browser`. Companion resolves it from its operating-system webview locale, not from the remote browser.\n- Localization has its own canonical payload digest and user scope. An unchanged section is not written again.\n- Pairing, login, and an explicit persisted preference change can change the active user. Periodic checks and reconnects cannot switch users.\n- Rust persists localization atomically, and native windows mirror effective values into local storage for fast startup.\n- Open windows receive localization update events. A new window reads the current native state.\n- The stored update timestamp is diagnostic data, not an ordering credential.\n- A failed section keeps its last valid values and reports delivery failure independently of directory search.\n\nThe separate localhost localization endpoint is retired. Incompatible clients must update; do not restore a parallel synchronizer.\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/frontend-logging-and-tracing", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "frontend-logging-and-tracing", "title": "Frontend Logging And Tracing", "path": "developer-guide/cross-cutting-systems/frontend-logging-and-tracing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.8": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.9": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "1.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "2.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.8": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.9": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "1.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "2.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/testing-and-quality-gates", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "testing-and-quality-gates", "title": "Testing and Quality Gates", "path": "developer-guide/testing-and-quality-gates", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "0.8": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "0.9": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "1.0": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "2.0": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/test-strategy-overview", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "test-strategy-overview", "title": "Test Strategy Overview", "path": "developer-guide/testing-and-quality-gates/test-strategy-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 29, "diff_removed": 4}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 8, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, companion, and archive-topology suites together. It stops at the first failed check so you can fix that subsystem before spending time on later suites. The order is backend type checking and tests, frontend type checking, linting, and tests, companion checks and tests, then archive-specific topology verification. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.8": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.9": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "1.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "2.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n### Frontend Console Diagnostics\n\nFrontend Vitest tests fail on every unexpected `console.warn` or `console.error` message, not only known React, MUI, or MSW warnings. The shared test setup records these messages until test cleanup is complete. Clearing or restoring Vitest mocks does not clear recorded diagnostics.\n\nFix the cause of unexpected output. Await asynchronous React updates with `act`, complete pending operations, and unmount components before restoring their API mocks.\n\nIf an error-path test must emit an expected diagnostic, mock that specific message and assert that it occurred. Forward unrelated messages to the original console method. Do not suppress all warnings or errors to make a test pass. Informational `console.log` output is not affected by this policy.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n"}, "page_contents": {"0.7": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, companion, and archive-topology suites together. It stops at the first failed check so you can fix that subsystem before spending time on later suites. The order is backend type checking and tests, frontend type checking, linting, and tests, companion checks and tests, then archive-specific topology verification. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.8": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.9": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "1.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "2.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n### Frontend Console Diagnostics\n\nFrontend Vitest tests fail on every unexpected `console.warn` or `console.error` message, not only known React, MUI, or MSW warnings. The shared test setup records these messages until test cleanup is complete. Clearing or restoring Vitest mocks does not clear recorded diagnostics.\n\nFix the cause of unexpected output. Await asynchronous React updates with `act`, complete pending operations, and unmount components before restoring their API mocks.\n\nIf an error-path test must emit an expected diagnostic, mock that specific message and assert that it occurred. Forward unrelated messages to the original console method. Do not suppress all warnings or errors to make a test pass. Informational `console.log` output is not affected by this policy.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/image-conversion-test-assets", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "image-conversion-test-assets", "title": "Image Conversion Test Assets", "path": "developer-guide/testing-and-quality-gates/image-conversion-test-assets", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.8": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.9": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "1.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "2.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.8": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.9": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "1.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "2.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "ci-workflows-and-repository-automation", "title": "Ci Workflows And Repository Automation", "path": "developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 26, "diff_removed": 2}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 15, "diff_removed": 1}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 47, "diff_removed": 31}}, "content_versions": {"0.7": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n\n", "0.8": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "0.9": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "1.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "2.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Maintenance: Clean Up Actions Caches` | `.github/workflows/cleanup-actions-caches.yml` | Removes closed-PR caches and superseded known cache keys without disabling warm caches for active builds. |\n| `Maintenance: Signal Closed PR Cache Cleanup` | `.github/workflows/signal-closed-pr-cache-cleanup.yml` | Triggers cache cleanup after a pull request closes without granting the pull request write access. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend, including Chromium and Firefox browser correctness\n- companion\n- website documentation\n\nManual dispatch runs all areas. Changes to shared frontend CI infrastructure also select frontend validation.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs. Require `CI: Test / test-gate` in the repository's branch protection or ruleset. A failed browser check fails the selected frontend job and therefore the gate; browser correctness doesn't wait for Docker image creation.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nBackend pytest runs treat unexpected warnings as errors, including resource-cleanup warnings. The shared policy in `backend/pyproject.toml` applies to both local and CI runs, and warning summaries aren't suppressed. Tests that deliberately trigger a warning must assert it with `pytest.warns(...)`, matching the warning category and message. Fix application warnings rather than ignoring them. Unavoidable dependency exceptions must be narrowly scoped and documented; the current exception covers Starlette's TestClient reference to AnyIO's deprecated `BlockingPortal` alias. Remove that exception when the dependency no longer needs it.\n\nThe `frontend` job requires a clean TypeScript check, runs Vitest, builds normal production assets, installs version-matched Playwright Chromium/Firefox binaries and their Linux dependencies, then runs `npm run test:browser:ci`. Both engines run on frontend pull requests, pushes, and manual dispatch. The same required checks run in release fallback when successful source CI cannot be reused.\n\nThe browser command requires exactly 16 production cases: four scenarios at desktop and narrow widths in each engine. They protect real normalization/syntax workers, entity decoding, native selection/focus/heading links/search, regex replacement with undo/redo and exact Save content, and cancellation/reopen cleanup with stale-result replay. Two additional development-worker cases exercise Vite's dependency-resolution path. Browser APIs and workers are real; backend responses are mocked at `http://localhost:3000/browse/smb/demo`. This isn't full-stack SMB E2E or evidence of physical printing, browser-menu Find, hardware IME, or assistive-technology behavior.\n\nThe correctness reporter rejects missing, duplicate, skipped, failed, and retried cases. Browser cases run with one worker and no retries. Reports and retained failure traces/screenshots are uploaded for seven days. Timing budgets, profiling, heap measurements, alternate renderers, and repeated cache/performance matrices remain separate opt-in diagnostics.\n\n`npm run typecheck` runs `tsc -b --noEmit` across the application, test/helper, and Node configuration projects. Browser code uses browser types; tests add Vitest and Node types; configuration tooling uses Node types. All source and declaration files remain checked with strict null/index and unused-code diagnostics enabled. The ES2023 library declarations describe existing APIs; the emitted target remains ES2020, and declarations don't provide runtime polyfills.\n\nType correctness is mandatory in routine CI, release fallback, ordinary `npm run build`, `./scripts/test`, and the VS Code frontend validation task. The old root `tsc --noEmit` command checked no input files and mustn't be used as a substitute. Regression tests protect required command wiring, strict options, separate environments, and complete source coverage. Unit and browser correctness remain independent required gates.\n\nThe required gate rejects an unexpectedly skipped selected job. Only unrelated, unselected areas may be skipped. Superseded pull-request test/lint runs are cancelled; main-branch validation runs aren't cancelled by that policy. Release reuse requires the exact source commit's successful frontend job, its successful browser-correctness step, and the new required `Verify frontend type correctness` step. Missing, skipped, or failed steps and legacy advisory type-check runs don't qualify.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and the archive topology conformance script, including Rust tests, formatting, and Clippy.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- GitHub Actions BuildKit caching for the `backend-test` Docker target, with dependency layers before source copies.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- Rust build caching for `companion/src-tauri`.\n\nFrontend jobs use clean `npm ci --prefer-offline` installs; they don't cache `node_modules` or Playwright browser downloads. The mypy cache inside the disposable backend test container isn't persisted separately.\n\nVitest file parallelism is capped at four workers and further limited by the runner's available CPUs and RAM, reserving 2 GiB plus 2 GiB per worker. The CI command logs the actual resources and selected cap. Standard public Ubuntu runners currently provide 4 vCPUs/16 GB RAM; private runners provide 2 vCPUs/8 GB RAM. Local measurements on a larger machine aren't Actions performance guarantees.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Cache Retention\n\n`Maintenance: Clean Up Actions Caches` runs after cache-producing workflows finish and daily as a fallback. When a pull request closes, an unprivileged signal workflow runs first; its completion triggers the same cleanup. A manual run defaults to a dry run; select **Delete eligible caches** to apply the policy. Its run summary lists selected entries and the amount of storage reclaimed. The cleanup reads only trusted code from `main`, and does not run pull-request code with cache-deletion permissions.\n\nThe policy keeps the newest known cache family on `main` and each open pull request. It removes superseded Rust and website cache keys, and deletes all caches for a closed pull request after its builds finish. It skips refs with active builds and leaves unrecognized keys, including individual BuildKit blobs on active refs, alone. GitHub's normal expiration still applies to those unclassified entries. The job deletes caches by ID so a pull request's copy cannot inadvertently delete an identically keyed cache on `main`.\n\nReview the dry-run report before changing cache-family rules. If active caches alone approach the repository storage limit, raise the limit or accept more cache misses: deleting their newest copies would make CI slower. Cleanup happens after cache uploads, so it cannot prevent a full repository from evicting caches during an upload.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm run test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:ci` for runner-aware Vitest concurrency\n- `cd frontend \u0026\u0026 npm run typecheck` for the complete strict compiler check\n- `cd frontend \u0026\u0026 npm run build` followed by `npm run test:browser:ci` for the exact production/development browser contract\n- `cd frontend \u0026\u0026 npm run test:e2e:install -- --with-deps` to install the matching browsers and Linux dependencies\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nRuff's executable-script rules (`EXE`) also check Python files throughout the repository, including `.github/`. Any Python-file change selects backend lint, as do changes to the lint workflow or `scripts/test`. These checks fail CI and `./scripts/test` on errors; they aren't advisory. A script with a shebang must be executable. Files invoked explicitly through Python, and imported modules, don't need a shebang.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nAll Ubuntu x64 host jobs use `ubuntu-latest`, following GitHub's managed OS migrations and runner-image updates. Native ARM64 image matrices use `ubuntu-26.04-arm`; GitHub doesn't currently document an `ubuntu-latest-arm` label. Windows and macOS coverage remains on its own platform runners.\n\nHost runner choice doesn't replace production-runtime validation. Debian-family checks still include the backend test container and the release `validate-tests` container.\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nThe release `validate-tests` job runs as root and sets `HOME=/root` at job scope. GitHub Actions can otherwise supply a mounted home directory owned by another user, which Firefox refuses to use. The override keeps dependency installation, Playwright browser installation, and browser execution on the same owned home. Hosted frontend PR checks keep the runner's normal home; don't apply `/root` globally or change ownership of GitHub's mounted directories.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n"}, "page_contents": {"0.7": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n\n", "0.8": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "0.9": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "1.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "2.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Maintenance: Clean Up Actions Caches` | `.github/workflows/cleanup-actions-caches.yml` | Removes closed-PR caches and superseded known cache keys without disabling warm caches for active builds. |\n| `Maintenance: Signal Closed PR Cache Cleanup` | `.github/workflows/signal-closed-pr-cache-cleanup.yml` | Triggers cache cleanup after a pull request closes without granting the pull request write access. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend, including Chromium and Firefox browser correctness\n- companion\n- website documentation\n\nManual dispatch runs all areas. Changes to shared frontend CI infrastructure also select frontend validation.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs. Require `CI: Test / test-gate` in the repository's branch protection or ruleset. A failed browser check fails the selected frontend job and therefore the gate; browser correctness doesn't wait for Docker image creation.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nBackend pytest runs treat unexpected warnings as errors, including resource-cleanup warnings. The shared policy in `backend/pyproject.toml` applies to both local and CI runs, and warning summaries aren't suppressed. Tests that deliberately trigger a warning must assert it with `pytest.warns(...)`, matching the warning category and message. Fix application warnings rather than ignoring them. Unavoidable dependency exceptions must be narrowly scoped and documented; the current exception covers Starlette's TestClient reference to AnyIO's deprecated `BlockingPortal` alias. Remove that exception when the dependency no longer needs it.\n\nThe `frontend` job requires a clean TypeScript check, runs Vitest, builds normal production assets, installs version-matched Playwright Chromium/Firefox binaries and their Linux dependencies, then runs `npm run test:browser:ci`. Both engines run on frontend pull requests, pushes, and manual dispatch. The same required checks run in release fallback when successful source CI cannot be reused.\n\nThe browser command requires exactly 16 production cases: four scenarios at desktop and narrow widths in each engine. They protect real normalization/syntax workers, entity decoding, native selection/focus/heading links/search, regex replacement with undo/redo and exact Save content, and cancellation/reopen cleanup with stale-result replay. Two additional development-worker cases exercise Vite's dependency-resolution path. Browser APIs and workers are real; backend responses are mocked at `http://localhost:3000/browse/smb/demo`. This isn't full-stack SMB E2E or evidence of physical printing, browser-menu Find, hardware IME, or assistive-technology behavior.\n\nThe correctness reporter rejects missing, duplicate, skipped, failed, and retried cases. Browser cases run with one worker and no retries. Reports and retained failure traces/screenshots are uploaded for seven days. Timing budgets, profiling, heap measurements, alternate renderers, and repeated cache/performance matrices remain separate opt-in diagnostics.\n\n`npm run typecheck` runs `tsc -b --noEmit` across the application, test/helper, and Node configuration projects. Browser code uses browser types; tests add Vitest and Node types; configuration tooling uses Node types. All source and declaration files remain checked with strict null/index and unused-code diagnostics enabled. The ES2023 library declarations describe existing APIs; the emitted target remains ES2020, and declarations don't provide runtime polyfills.\n\nType correctness is mandatory in routine CI, release fallback, ordinary `npm run build`, `./scripts/test`, and the VS Code frontend validation task. The old root `tsc --noEmit` command checked no input files and mustn't be used as a substitute. Regression tests protect required command wiring, strict options, separate environments, and complete source coverage. Unit and browser correctness remain independent required gates.\n\nThe required gate rejects an unexpectedly skipped selected job. Only unrelated, unselected areas may be skipped. Superseded pull-request test/lint runs are cancelled; main-branch validation runs aren't cancelled by that policy. Release reuse requires the exact source commit's successful frontend job, its successful browser-correctness step, and the new required `Verify frontend type correctness` step. Missing, skipped, or failed steps and legacy advisory type-check runs don't qualify.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and the archive topology conformance script, including Rust tests, formatting, and Clippy.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- GitHub Actions BuildKit caching for the `backend-test` Docker target, with dependency layers before source copies.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- Rust build caching for `companion/src-tauri`.\n\nFrontend jobs use clean `npm ci --prefer-offline` installs; they don't cache `node_modules` or Playwright browser downloads. The mypy cache inside the disposable backend test container isn't persisted separately.\n\nVitest file parallelism is capped at four workers and further limited by the runner's available CPUs and RAM, reserving 2 GiB plus 2 GiB per worker. The CI command logs the actual resources and selected cap. Standard public Ubuntu runners currently provide 4 vCPUs/16 GB RAM; private runners provide 2 vCPUs/8 GB RAM. Local measurements on a larger machine aren't Actions performance guarantees.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Cache Retention\n\n`Maintenance: Clean Up Actions Caches` runs after cache-producing workflows finish and daily as a fallback. When a pull request closes, an unprivileged signal workflow runs first; its completion triggers the same cleanup. A manual run defaults to a dry run; select **Delete eligible caches** to apply the policy. Its run summary lists selected entries and the amount of storage reclaimed. The cleanup reads only trusted code from `main`, and does not run pull-request code with cache-deletion permissions.\n\nThe policy keeps the newest known cache family on `main` and each open pull request. It removes superseded Rust and website cache keys, and deletes all caches for a closed pull request after its builds finish. It skips refs with active builds and leaves unrecognized keys, including individual BuildKit blobs on active refs, alone. GitHub's normal expiration still applies to those unclassified entries. The job deletes caches by ID so a pull request's copy cannot inadvertently delete an identically keyed cache on `main`.\n\nReview the dry-run report before changing cache-family rules. If active caches alone approach the repository storage limit, raise the limit or accept more cache misses: deleting their newest copies would make CI slower. Cleanup happens after cache uploads, so it cannot prevent a full repository from evicting caches during an upload.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm run test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:ci` for runner-aware Vitest concurrency\n- `cd frontend \u0026\u0026 npm run typecheck` for the complete strict compiler check\n- `cd frontend \u0026\u0026 npm run build` followed by `npm run test:browser:ci` for the exact production/development browser contract\n- `cd frontend \u0026\u0026 npm run test:e2e:install -- --with-deps` to install the matching browsers and Linux dependencies\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nRuff's executable-script rules (`EXE`) also check Python files throughout the repository, including `.github/`. Any Python-file change selects backend lint, as do changes to the lint workflow or `scripts/test`. These checks fail CI and `./scripts/test` on errors; they aren't advisory. A script with a shebang must be executable. Files invoked explicitly through Python, and imported modules, don't need a shebang.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nAll Ubuntu x64 host jobs use `ubuntu-latest`, following GitHub's managed OS migrations and runner-image updates. Native ARM64 image matrices use `ubuntu-26.04-arm`; GitHub doesn't currently document an `ubuntu-latest-arm` label. Windows and macOS coverage remains on its own platform runners.\n\nHost runner choice doesn't replace production-runtime validation. Debian-family checks still include the backend test container and the release `validate-tests` container.\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nThe release `validate-tests` job runs as root and sets `HOME=/root` at job scope. GitHub Actions can otherwise supply a mounted home directory owned by another user, which Firefox refuses to use. The override keeps dependency installation, Playwright browser installation, and browser execution on the same owned home. Hosted frontend PR checks keep the runner's normal home; don't apply `/root` globally or change ownership of GitHub's mounted directories.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/contribution-workflows", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "contribution-workflows", "title": "Contribution Workflows", "path": "developer-guide/contribution-workflows", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "0.8": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "0.9": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "1.0": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "2.0": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/contribution-workflows/how-to-plan-and-review-a-change", "parent_id": "section:developer-guide/contribution-workflows", "depth": 2, "kind": "page", "label": "how-to-plan-and-review-a-change", "title": "How To Plan And Review A Change", "path": "developer-guide/contribution-workflows/how-to-plan-and-review-a-change", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.8": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.9": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "1.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "2.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n"}, "page_contents": {"0.7": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.8": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.9": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "1.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "2.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/security", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "security", "title": "Security", "path": "developer-guide/security", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "0.8": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "0.9": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "1.0": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "2.0": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/security/dependency-security-and-dependabot", "parent_id": "section:developer-guide/security", "depth": 2, "kind": "page", "label": "dependency-security-and-dependabot", "title": "Dependency Security And Dependabot", "path": "developer-guide/security/dependency-security-and-dependabot", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 15, "diff_removed": 2}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 3, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.8": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.9": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "1.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "2.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/format-dependabot-pr-title.yml` | prefixes Dependabot pull request titles when configured group names omit them |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nchecks open Dependabot pull requests when a `CI: Test` run triggered by\nDependabot starts and finishes, and adds the matching prefix where needed. It runs trusted workflow code with pull-request write access, without using `pull_request_target` or checking out pull-request code. Run it manually to retry title formatting if a CI run did not trigger it. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.8": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.9": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "1.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "2.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/format-dependabot-pr-title.yml` | prefixes Dependabot pull request titles when configured group names omit them |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nchecks open Dependabot pull requests when a `CI: Test` run triggered by\nDependabot starts and finishes, and adds the matching prefix where needed. It runs trusted workflow code with pull-request write access, without using `pull_request_target` or checking out pull-request code. Run it manually to retry title formatting if a CI run did not trigger it. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/security/container-image-security-and-artifact-integrity", "parent_id": "section:developer-guide/security", "depth": 2, "kind": "page", "label": "container-image-security-and-artifact-integrity", "title": "Container Image Security And Artifact Integrity", "path": "developer-guide/security/container-image-security-and-artifact-integrity", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.8": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.9": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "1.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "2.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n"}, "page_contents": {"0.7": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.8": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.9": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "1.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "2.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/release-and-versioning", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "release-and-versioning", "title": "Release and Versioning", "path": "developer-guide/release-and-versioning", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 2, "diff_removed": 6}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the workflows where a small metadata mistake can create cross-boundary drift.\n\nFor a complete Sambee product release, start here:\n\n- [Release Checklist](./release-checklist/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nUse these pages when the goal is to take one reviewed commit all the way to `stable` without rebuilding at release time.\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n\nUse this section when you are changing version numbers, updating reviewed dependencies, or publishing a product release.\n", "0.8": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the workflows where a small metadata mistake can create cross-boundary drift.\n\nFor a complete Sambee product release, start here:\n\n- [Release Checklist](./release-checklist/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nUse these pages when the goal is to take one reviewed commit all the way to `stable` without rebuilding at release time.\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n\nUse this section when you are changing version numbers, updating reviewed dependencies, or publishing a product release.\n", "0.9": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n", "1.0": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n", "2.0": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/dependency-update-workflow", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "dependency-update-workflow", "title": "Dependency Update Workflow", "path": "developer-guide/release-and-versioning/dependency-update-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 2}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 12, "diff_removed": 14}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 138, "diff_removed": 4}}, "content_versions": {"0.7": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.8": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.9": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "1.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "2.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Frontend Install Freshness\n\n`./scripts/test` checks frontend dependency freshness before generating test\nfixtures or running backend tests. It stops if the install stamp is missing or\ndoesn't match the current `frontend/package.json` and\n`frontend/package-lock.json`. It doesn't install dependencies automatically or\nrequire network access for the check.\n\nTo restore the frontend environment, run this from the repository root:\n\n```bash\ncd frontend \u0026\u0026 npm ci\n```\n\nThe install lifecycle clears any previous stamp before setup and writes a SHA-256\nhash to `frontend/node_modules/.dependencies.sha256` only after the existing\npostinstall setup succeeds. The stamp is local to the installed environment and\nisn't committed. Existing installations need one successful `npm ci` to create\nit. Installations using `--ignore-scripts` won't create the stamp.\n\nTo check the environment separately, run:\n\n```bash\ncd frontend \u0026\u0026 npm run check:dependencies\n```\n\nThe hash covers both files in full, so metadata-only changes also require a fresh\ninstall. This check detects changed dependency inputs, not arbitrary damage to\ninstalled packages. If individual packages are missing despite a matching stamp,\nrun `npm ci` again.\n\n### Biome Version Alignment\n\n`npm run lint` in `frontend/` and `companion/` checks the Biome version before\nlinting source files. Each check requires an exact `@biomejs/biome` pin that\nmatches the lockfile and installed package. Both checks also require matching\npins and lockfile versions in both projects, and matching schemas in the\nrepository-root, frontend, and companion configurations. They don't require the\nother project's installed dependencies.\n\nTo run the checks separately from the repository root:\n\n```bash\nnpm --prefix frontend run check:biome\nnpm --prefix companion run check:biome\n```\n\nKeep both projects on the same Biome version because they share configuration.\nDependabot doesn't update `@biomejs/biome` in either project. Separate npm updates\ncan change a package version without migrating shared configurations. Update\nBiome manually, including security fixes, through this procedure:\n\n1. Set the same exact Biome version in both projects with\n\n\t```bash\n\tnpm --prefix frontend install --save-dev --save-exact @biomejs/biome@\u003cversion\u003e\n\tnpm --prefix companion install --save-dev --save-exact @biomejs/biome@\u003cversion\u003e\n\t```\n\n1. From the repository root, run the installed frontend binary:\n\n\t```bash\n\tfrontend/node_modules/.bin/biome migrate --write\n\t```\n\n1. Review migration requirements for `frontend/biome.json` and\n\t`companion/biome.json`. Apply required setting changes and update their\n\tschemas to the same version. Biome migrates the root configuration but\n\tdoesn't rewrite these non-root configurations. An explicit non-root\n\t`--config-path` is rejected.\n1. Run both `check:biome` commands above and both projects' `npm run lint`.\n1. Include both package manifests, both lockfiles, and all three configurations\n\tin the same change.\n\nIf only the installed version is stale, run `npm ci` in the affected project.\nIf committed pins, locks, or schemas differ, repair them through the coordinated\nprocedure; `npm ci` cannot fix that mismatch. The checks don't install\ndependencies or change configuration files. Dependency security audits still\napply to manually maintained Biome versions.\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. It also\nruns pip with `--dry-run --ignore-installed --require-hashes` for each lockfile.\nThis checks transitive compatibility and hashes without using installed packages\nor changing committed versions. The backend test image and production Docker\nimage validate actual hash-enforced installations.\n\nDependabot doesn't update `pydantic`, `pydantic-core`, or `pydantic-settings`.\nUpdate this package family manually. Pydantic requires an exact core version;\nthe previous core-only ignore rule still allowed Pydantic updates to leave an\nincompatible core pin in both lockfiles. Grouping packages alone doesn't ensure\nthat generated locks contain compatible transitive versions.\n\nFor a Pydantic update or a broken dependency-update pull request:\n\n1. Review and update the direct pins in `backend/requirements.txt` as needed.\n1. Run `scripts/refresh-backend-lockfiles --keep-existing` from the repository root.\n1. Review both generated locks. The resolver keeps existing versions where\n\tcompatible and changes dependencies required by the source pins.\n1. Run backend tests and type checking before merging. Don't force a core pin or\n\tedit its hashes manually.\n\nSecurity findings for this package family need a manual update through the same\nprocedure. The ignore rules don't replace dependency security audits.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests. Add `--keep-existing` to check resolution while keeping compatible\ncommitted versions. This command compares generated file content; it isn't a\nreplacement for the CI pip resolution checks.\n\n### Container Build Pip\n\n`backend/build-tools/requirements.txt` pins the build-time pip version and its\nwheel SHA-256 hash. Keep this file separate from the application lockfiles.\nDependabot checks this directory each week and can update the version and hashes\nin one pull request. Don't copy the pin or download checksum into the Dockerfile.\n\nBefore Python dependency downloads, `scripts/bootstrap-build-pip.py` fetches the\npinned wheel through Python's standard-library HTTPS client and the system CA\nstore. It checks the wheel against the committed hashes, then runs that wheel\ndirectly to install pip offline. The old pip isn't used for the download or\nupgrade. The shared runtime, native `pyvips` wheel builder, and backend-test\nvirtual environment all use this bootstrap step.\n\nThe production target installs the application dependencies, runs `pip check`,\nthen uninstalls pip and removes Python's separate `ensurepip` bootstrap copy.\nThe test, beta, and stable channels use this same production image. They can't\ninstall packages with pip at runtime; change the dependency inputs and rebuild\nthe image instead. Development and backend-test targets keep pip.\n\nThe upgrade and cleanup steps are cached before application source is copied.\nUncached builds need a pip download, but application-only builds can reuse the\ndependency layer. Files from the base image can remain in older image layers,\neven after they're removed from the final filesystem.\n\nFor build-pip updates:\n\n- Run `backend/.venv/bin/python -m pytest backend/tests/test_bootstrap_build_pip_script.py`.\n- Validate startup and the absence of pip, its launchers and metadata, and `ensurepip` in both production image architectures.\n- Run the container vulnerability scan. A pip release can still include vulnerable bundled libraries; a version update alone doesn't prove that all findings are fixed.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm run typecheck \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.8": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.9": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "1.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "2.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Frontend Install Freshness\n\n`./scripts/test` checks frontend dependency freshness before generating test\nfixtures or running backend tests. It stops if the install stamp is missing or\ndoesn't match the current `frontend/package.json` and\n`frontend/package-lock.json`. It doesn't install dependencies automatically or\nrequire network access for the check.\n\nTo restore the frontend environment, run this from the repository root:\n\n```bash\ncd frontend \u0026\u0026 npm ci\n```\n\nThe install lifecycle clears any previous stamp before setup and writes a SHA-256\nhash to `frontend/node_modules/.dependencies.sha256` only after the existing\npostinstall setup succeeds. The stamp is local to the installed environment and\nisn't committed. Existing installations need one successful `npm ci` to create\nit. Installations using `--ignore-scripts` won't create the stamp.\n\nTo check the environment separately, run:\n\n```bash\ncd frontend \u0026\u0026 npm run check:dependencies\n```\n\nThe hash covers both files in full, so metadata-only changes also require a fresh\ninstall. This check detects changed dependency inputs, not arbitrary damage to\ninstalled packages. If individual packages are missing despite a matching stamp,\nrun `npm ci` again.\n\n### Biome Version Alignment\n\n`npm run lint` in `frontend/` and `companion/` checks the Biome version before\nlinting source files. Each check requires an exact `@biomejs/biome` pin that\nmatches the lockfile and installed package. Both checks also require matching\npins and lockfile versions in both projects, and matching schemas in the\nrepository-root, frontend, and companion configurations. They don't require the\nother project's installed dependencies.\n\nTo run the checks separately from the repository root:\n\n```bash\nnpm --prefix frontend run check:biome\nnpm --prefix companion run check:biome\n```\n\nKeep both projects on the same Biome version because they share configuration.\nDependabot doesn't update `@biomejs/biome` in either project. Separate npm updates\ncan change a package version without migrating shared configurations. Update\nBiome manually, including security fixes, through this procedure:\n\n1. Set the same exact Biome version in both projects with\n\n\t```bash\n\tnpm --prefix frontend install --save-dev --save-exact @biomejs/biome@\u003cversion\u003e\n\tnpm --prefix companion install --save-dev --save-exact @biomejs/biome@\u003cversion\u003e\n\t```\n\n1. From the repository root, run the installed frontend binary:\n\n\t```bash\n\tfrontend/node_modules/.bin/biome migrate --write\n\t```\n\n1. Review migration requirements for `frontend/biome.json` and\n\t`companion/biome.json`. Apply required setting changes and update their\n\tschemas to the same version. Biome migrates the root configuration but\n\tdoesn't rewrite these non-root configurations. An explicit non-root\n\t`--config-path` is rejected.\n1. Run both `check:biome` commands above and both projects' `npm run lint`.\n1. Include both package manifests, both lockfiles, and all three configurations\n\tin the same change.\n\nIf only the installed version is stale, run `npm ci` in the affected project.\nIf committed pins, locks, or schemas differ, repair them through the coordinated\nprocedure; `npm ci` cannot fix that mismatch. The checks don't install\ndependencies or change configuration files. Dependency security audits still\napply to manually maintained Biome versions.\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. It also\nruns pip with `--dry-run --ignore-installed --require-hashes` for each lockfile.\nThis checks transitive compatibility and hashes without using installed packages\nor changing committed versions. The backend test image and production Docker\nimage validate actual hash-enforced installations.\n\nDependabot doesn't update `pydantic`, `pydantic-core`, or `pydantic-settings`.\nUpdate this package family manually. Pydantic requires an exact core version;\nthe previous core-only ignore rule still allowed Pydantic updates to leave an\nincompatible core pin in both lockfiles. Grouping packages alone doesn't ensure\nthat generated locks contain compatible transitive versions.\n\nFor a Pydantic update or a broken dependency-update pull request:\n\n1. Review and update the direct pins in `backend/requirements.txt` as needed.\n1. Run `scripts/refresh-backend-lockfiles --keep-existing` from the repository root.\n1. Review both generated locks. The resolver keeps existing versions where\n\tcompatible and changes dependencies required by the source pins.\n1. Run backend tests and type checking before merging. Don't force a core pin or\n\tedit its hashes manually.\n\nSecurity findings for this package family need a manual update through the same\nprocedure. The ignore rules don't replace dependency security audits.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests. Add `--keep-existing` to check resolution while keeping compatible\ncommitted versions. This command compares generated file content; it isn't a\nreplacement for the CI pip resolution checks.\n\n### Container Build Pip\n\n`backend/build-tools/requirements.txt` pins the build-time pip version and its\nwheel SHA-256 hash. Keep this file separate from the application lockfiles.\nDependabot checks this directory each week and can update the version and hashes\nin one pull request. Don't copy the pin or download checksum into the Dockerfile.\n\nBefore Python dependency downloads, `scripts/bootstrap-build-pip.py` fetches the\npinned wheel through Python's standard-library HTTPS client and the system CA\nstore. It checks the wheel against the committed hashes, then runs that wheel\ndirectly to install pip offline. The old pip isn't used for the download or\nupgrade. The shared runtime, native `pyvips` wheel builder, and backend-test\nvirtual environment all use this bootstrap step.\n\nThe production target installs the application dependencies, runs `pip check`,\nthen uninstalls pip and removes Python's separate `ensurepip` bootstrap copy.\nThe test, beta, and stable channels use this same production image. They can't\ninstall packages with pip at runtime; change the dependency inputs and rebuild\nthe image instead. Development and backend-test targets keep pip.\n\nThe upgrade and cleanup steps are cached before application source is copied.\nUncached builds need a pip download, but application-only builds can reuse the\ndependency layer. Files from the base image can remain in older image layers,\neven after they're removed from the final filesystem.\n\nFor build-pip updates:\n\n- Run `backend/.venv/bin/python -m pytest backend/tests/test_bootstrap_build_pip_script.py`.\n- Validate startup and the absence of pip, its launchers and metadata, and `ensurepip` in both production image architectures.\n- Run the container vulnerability scan. A pip release can still include vulnerable bundled libraries; a version update alone doesn't prove that all findings are fixed.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm run typecheck \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/product-versioning", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "product-versioning", "title": "Product Versioning", "path": "developer-guide/release-and-versioning/product-versioning", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 13, "diff_removed": 18}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.8": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.9": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "1.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "2.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.8": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.9": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "1.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "2.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/release-checklist", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "release-checklist", "title": "Release Checklist", "path": "developer-guide/release-and-versioning/release-checklist", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {"0.7": "+++\ntitle = \"Release Checklist\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Release Checklist\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n"}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/docker-release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "docker-release-overview", "title": "Docker Release Overview", "path": "developer-guide/release-and-versioning/docker-release-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 30, "diff_removed": 45}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.8": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.9": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "1.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "2.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.8": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.9": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "1.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "2.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/build-docker-image", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "build-docker-image", "title": "Build Docker Image", "path": "developer-guide/release-and-versioning/build-docker-image", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 23, "diff_removed": 28}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 3, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.8": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.9": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "1.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "2.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow requires the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nFor source checks, the workflow reuses successful backend and frontend jobs from `CI: Test` only when they ran on a push to `main` for the exact candidate commit. It checks each job separately. If a job was skipped, is still running, or its result cannot be verified, the release workflow runs that area's checks itself. PR checks alone do not qualify because they may test a different merge commit. Platform image builds and startup checks always run for a new candidate.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.8": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.9": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "1.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "2.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow requires the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nFor source checks, the workflow reuses successful backend and frontend jobs from `CI: Test` only when they ran on a push to `main` for the exact candidate commit. It checks each job separately. If a job was skipped, is still running, or its result cannot be verified, the release workflow runs that area's checks itself. PR checks alone do not qualify because they may test a different merge commit. Platform image builds and startup checks always run for a new candidate.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/promote-docker-image", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "promote-docker-image", "title": "Promote Docker Image", "path": "developer-guide/release-and-versioning/promote-docker-image", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 32}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.8": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.9": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "1.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "2.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.8": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.9": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "1.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "2.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/docker-backfill-and-cleanup", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "docker-backfill-and-cleanup", "title": "Docker Backfill And Cleanup", "path": "developer-guide/release-and-versioning/docker-backfill-and-cleanup", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.8": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.9": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "1.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "2.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.8": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.9": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "1.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "2.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-release-overview", "title": "Companion Release Overview", "path": "developer-guide/release-and-versioning/companion-release-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 4, "diff_removed": 0}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 25, "diff_removed": 20}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 14, "diff_removed": 47}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 3, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.8": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Local Linux-hosted cross-checks can validate Windows-target compatibility, but they do not replace the Windows CI release build.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.9": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - builds Companion\n   - signs the build artifacts\n   - creates one immutable draft release in in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - assigns a `companion-vX.Y.Z` tag to the draft release.\n1. Test the draft release.\n   - Download the installer from the release's artifacts, install and test.\n1. Publish the draft release. This:\n   - Makes the release eligible for promotion to the `test`, `beta`, and `stable` channels.\n   - Prevents additional build workflow runs changing the published Companion release.\n1. Ensure that a matching published public Sambee release `vX.Y.Z` exists.\n   - This authorizes the Companion workflow to promote a release.\n1. To promote the release to the update channels, run `Release: Promote Companion Release`:\n   - Select the channels: `test`, `beta`, and/or `stable`.\n   - Select whether to update the Sambee download metadata.\n\nThe workflow uses `build`, `recover-finalizer`, and `complete` states. A matching incomplete draft resumes only from recorded retained Actions artifacts; a complete draft or published release is not rebuilt. When a replacement is needed, increment `Z`, synchronize, commit on `main`, and build a new candidate.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set and creates, resumes, or reports the immutable draft GitHub Release in `helgeklein/sambee-companion`. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source and creates or resumes one draft release for its immutable tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Increment the `Z` build sequence when you need another candidate.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "1.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n", "2.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/sambee-app/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.8": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Local Linux-hosted cross-checks can validate Windows-target compatibility, but they do not replace the Windows CI release build.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.9": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - builds Companion\n   - signs the build artifacts\n   - creates one immutable draft release in in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - assigns a `companion-vX.Y.Z` tag to the draft release.\n1. Test the draft release.\n   - Download the installer from the release's artifacts, install and test.\n1. Publish the draft release. This:\n   - Makes the release eligible for promotion to the `test`, `beta`, and `stable` channels.\n   - Prevents additional build workflow runs changing the published Companion release.\n1. Ensure that a matching published public Sambee release `vX.Y.Z` exists.\n   - This authorizes the Companion workflow to promote a release.\n1. To promote the release to the update channels, run `Release: Promote Companion Release`:\n   - Select the channels: `test`, `beta`, and/or `stable`.\n   - Select whether to update the Sambee download metadata.\n\nThe workflow uses `build`, `recover-finalizer`, and `complete` states. A matching incomplete draft resumes only from recorded retained Actions artifacts; a complete draft or published release is not rebuilt. When a replacement is needed, increment `Z`, synchronize, commit on `main`, and build a new candidate.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set and creates, resumes, or reports the immutable draft GitHub Release in `helgeklein/sambee-companion`. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source and creates or resumes one draft release for its immutable tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Increment the `Z` build sequence when you need another candidate.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "1.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n", "2.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/sambee-app/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/build-companion-release", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "build-companion-release", "title": "Build Companion Release", "path": "developer-guide/release-and-versioning/build-companion-release", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 27, "diff_removed": 83}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 25, "diff_removed": 39}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.8": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.9": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create Companion release assets for one immutable build version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It creates builds for the selected platforms, which are then uploaded to the GitHub draft release by a finalizer.\n\n## Input\n\nThe manual workflow exposes an optional existing build-version selector plus one checkbox per platform:\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit with the `build-vX.Y.Z` tag. Leave empty to build the latest commit and set the `build-vX.Y.Z` tag on that commit. |\n| `build_all_platforms` | Include every supported platform in one run. |\n| `build_linux_x64` | Include the Linux x64 build. |\n| `build_macos_arm64` | Include the macOS ARM64 build. |\n| `build_windows_x64` | Include the Windows x64 build. |\n| `build_windows_arm64` | Include the Windows ARM64 build. |\n\nNew builds must be dispatched from `main`. The workflow verifies synchronized metadata, reserves `build-vX.Y.Z` for the exact source commit, and rejects any version that is not plain numeric `X.Y.Z`. It never changes an existing build tag.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the canonical `build-vX.Y.Z` source commit or assigns it to the latest commit.\n3. Verifies synchronized version metadata.\n4. Builds the platform matrix derived from the checked boxes.\n5. Writes a per-platform artifact manifest with package names, SHA-256 checksums, installer/updater/signature roles, platform, and target; then uploads uniquely named private Actions artifacts.\n6. The finalizer downloads every retained artifact, verifies the manifests and complete package sets, writes a public aggregate manifest, provenance, and completion marker, then creates or resumes the external draft release.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Build Output\n\nThe finalizer uploads assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- A public aggregate artifact manifest, uploaded before all package assets.\n- Release provenance and a completion marker binding the release tag, aggregate-manifest digest, provenance digest, and exact expected assets.\n\n### Recovery And Immutability\n\nThe draft GitHub release is immutable once any asset is present: the finalizer uploads a missing asset or accepts an existing byte-identical asset, and rejects a conflicting replacement.\n\nIf a finalizer is interrupted, a later run uses the exact retained Actions artifact IDs, digests, originating run ID, run attempt, platform, and target recorded in draft provenance. It does not rebuild matrix artifacts. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the `companion-release-publication` lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it never reached a publication step.\n\n## Review and Publish\n\nReview the draft GitHub release created or updated by this workflow. Then publish it.\n\nPublishing assigns the tag `companion-vX.Y.Z`.\n", "1.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy.", "2.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy."}, "page_contents": {"0.7": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.8": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.9": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create Companion release assets for one immutable build version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It creates builds for the selected platforms, which are then uploaded to the GitHub draft release by a finalizer.\n\n## Input\n\nThe manual workflow exposes an optional existing build-version selector plus one checkbox per platform:\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit with the `build-vX.Y.Z` tag. Leave empty to build the latest commit and set the `build-vX.Y.Z` tag on that commit. |\n| `build_all_platforms` | Include every supported platform in one run. |\n| `build_linux_x64` | Include the Linux x64 build. |\n| `build_macos_arm64` | Include the macOS ARM64 build. |\n| `build_windows_x64` | Include the Windows x64 build. |\n| `build_windows_arm64` | Include the Windows ARM64 build. |\n\nNew builds must be dispatched from `main`. The workflow verifies synchronized metadata, reserves `build-vX.Y.Z` for the exact source commit, and rejects any version that is not plain numeric `X.Y.Z`. It never changes an existing build tag.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the canonical `build-vX.Y.Z` source commit or assigns it to the latest commit.\n3. Verifies synchronized version metadata.\n4. Builds the platform matrix derived from the checked boxes.\n5. Writes a per-platform artifact manifest with package names, SHA-256 checksums, installer/updater/signature roles, platform, and target; then uploads uniquely named private Actions artifacts.\n6. The finalizer downloads every retained artifact, verifies the manifests and complete package sets, writes a public aggregate manifest, provenance, and completion marker, then creates or resumes the external draft release.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Build Output\n\nThe finalizer uploads assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- A public aggregate artifact manifest, uploaded before all package assets.\n- Release provenance and a completion marker binding the release tag, aggregate-manifest digest, provenance digest, and exact expected assets.\n\n### Recovery And Immutability\n\nThe draft GitHub release is immutable once any asset is present: the finalizer uploads a missing asset or accepts an existing byte-identical asset, and rejects a conflicting replacement.\n\nIf a finalizer is interrupted, a later run uses the exact retained Actions artifact IDs, digests, originating run ID, run attempt, platform, and target recorded in draft provenance. It does not rebuild matrix artifacts. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the `companion-release-publication` lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it never reached a publication step.\n\n## Review and Publish\n\nReview the draft GitHub release created or updated by this workflow. Then publish it.\n\nPublishing assigns the tag `companion-vX.Y.Z`.\n", "1.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy.", "2.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/promote-companion-release", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "promote-companion-release", "title": "Promote Companion Release", "path": "developer-guide/release-and-versioning/promote-companion-release", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 1}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 18, "diff_removed": 16}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 2, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.8": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.9": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nThe workflow reads the selected release's immutable provenance and derives the required public Sambee authorization tag as `vX.Y.Z`. That public release must contain `sambee-release.json` with a matching version, build tag, source SHA, and Companion-compatible scope.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The public `sambee-release.json` does not authorize `companion` or `both`, or its version, build tag, or source SHA differs from the Companion provenance.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow derive the matching public Sambee release, then update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "1.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `helgeklein/sambee-companion`, such as `https://github.com/helgeklein/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "2.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `sambee-app/sambee-companion`, such as `https://github.com/sambee-app/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `sambee-app/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.8": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.9": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nThe workflow reads the selected release's immutable provenance and derives the required public Sambee authorization tag as `vX.Y.Z`. That public release must contain `sambee-release.json` with a matching version, build tag, source SHA, and Companion-compatible scope.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The public `sambee-release.json` does not authorize `companion` or `both`, or its version, build tag, or source SHA differs from the Companion provenance.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow derive the matching public Sambee release, then update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "1.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `helgeklein/sambee-companion`, such as `https://github.com/helgeklein/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "2.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `sambee-app/sambee-companion`, such as `https://github.com/sambee-app/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `sambee-app/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both to make the same release available through self-update and direct download.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-channels-feeds-and-downloads", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-channels-feeds-and-downloads", "title": "Companion Channels Feeds And Downloads", "path": "developer-guide/release-and-versioning/companion-channels-feeds-and-downloads", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 1}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 6, "diff_removed": 11}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 1, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.8": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.9": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new `Z` version instead.\n- Treat `test`, `beta`, and `stable` as visibility pointers, never as different binaries or version suffixes.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "1.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n", "2.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `sambee-app/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.8": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.9": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new `Z` version instead.\n- Treat `test`, `beta`, and `stable` as visibility pointers, never as different binaries or version suffixes.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "1.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n", "2.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `sambee-app/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "release-overview", "title": "Release Overview", "path": "developer-guide/release-and-versioning/release-overview", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "authored"}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 58, "diff_removed": 21}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 20, "diff_removed": 13}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 2, "diff_removed": 2}}, "content_versions": {"0.8": "+++\ntitle = \"Release Overview\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n", "0.9": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Component Build \u0026 Release Process\n\n### Update Documentation\n\n1. Review the homepage content and update it where necessary.\n1. Docs:\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow creates a draft release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - Publish it.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds `X.Y` a version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `test`, `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "1.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/helgeklein/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "2.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/sambee-app/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/sambee-app/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n"}, "page_contents": {"0.8": "+++\ntitle = \"Release Overview\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n", "0.9": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Component Build \u0026 Release Process\n\n### Update Documentation\n\n1. Review the homepage content and update it where necessary.\n1. Docs:\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow creates a draft release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - Publish it.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds `X.Y` a version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `test`, `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "1.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/helgeklein/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "2.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/sambee-app/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/sambee-app/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-release-cleanup", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-release-cleanup", "title": "Companion Release Cleanup", "path": "developer-guide/release-and-versioning/companion-release-cleanup", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 1, "diff_removed": 2}}, "content_versions": {"1.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `helgeklein/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n\n", "2.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `sambee-app/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n"}, "page_contents": {"1.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `helgeklein/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n\n", "2.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `sambee-app/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "book:website-dev-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "website-dev-guide", "title": "Website Dev Guide", "path": "website-dev-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 0, "diff_removed": 2}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "0.8": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "0.9": "+++\ntitle = \"Website Dev Guide\"\n+++\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "1.0": "+++\ntitle = \"Website Dev Guide\"\n+++\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "2.0": "+++\ntitle = \"Website Dev Guide\"\n+++\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/docs-platform", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "docs-platform", "title": "Docs Platform", "path": "website-dev-guide/docs-platform", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/website-and-docs-architecture-overview", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "website-and-docs-architecture-overview", "title": "Website And Docs Architecture Overview", "path": "website-dev-guide/docs-platform/website-and-docs-architecture-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.8": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.9": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "1.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "2.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.8": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.9": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "1.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "2.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/docs-content-model-navigation-and-inheritance", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "docs-content-model-navigation-and-inheritance", "title": "Docs Content Model Navigation And Inheritance", "path": "website-dev-guide/docs-platform/docs-content-model-navigation-and-inheritance", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.8": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.9": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "1.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "2.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.8": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.9": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "1.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "2.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/docs-runtime-and-route-resolution", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "docs-runtime-and-route-resolution", "title": "Docs Runtime And Route Resolution", "path": "website-dev-guide/docs-platform/docs-runtime-and-route-resolution", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.8": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.9": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "1.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "2.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.8": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.9": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "1.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "2.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/authoring-and-tooling", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "authoring-and-tooling", "title": "Authoring and Tooling", "path": "website-dev-guide/authoring-and-tooling", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-authoring-workflow", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-authoring-workflow", "title": "Docs Authoring Workflow", "path": "website-dev-guide/authoring-and-tooling/docs-authoring-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.8": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.9": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "1.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "2.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n"}, "page_contents": {"0.7": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.8": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.9": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "1.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "2.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-style-guide", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-style-guide", "title": "Docs Style Guide", "path": "website-dev-guide/authoring-and-tooling/docs-style-guide", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.8": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.9": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "1.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "2.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.8": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.9": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "1.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "2.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language that sounds natural.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n### Words to Avoid\n\nThe following words have a weird or unnatural sound and are to be avoided:\n\n- outcome\n\n## User Guide: Value Without Unnecessary Detail\n\nThe user guide must show what Sambee helps users do, then explain only what they need to complete those tasks. It is not a tutorial on familiar browser, file manager, or editor controls.\n\n### Content Test\n\nKeep a passage only if it does at least one of the following:\n\n- Explains a concrete benefit or defines a relevant Sambee concept.\n- Explains a non-obvious Sambee action or behavior.\n- States a limit or requirement that affects the task.\n- Gives an actionable recovery step.\n\nOtherwise, remove it. Moving unnecessary detail to Reference does not make it useful. Administrator policy and implementation details belong in the appropriate guide, not in user task instructions.\n\n### Detail and Page Boundaries\n\n- Do not explain obvious actions such as opening a website, scrolling, typing, or using a clearly labeled standard button. Explain a control only when its behavior differs from what users expect.\n- Prefer a short explanation to a numbered procedure when the interface makes the sequence clear. Use steps for non-obvious workflows where order matters.\n- Keep small related topics together under clear headings. Create a separate page only when the topic has enough distinct user value or non-obvious behavior to need one.\n- Link to existing procedures and in-app help instead of repeating control lists or shortcut tables. Mention a shortcut when it helps with the specific task.\n- Keep important limits and data-safety warnings beside the relevant action. Explain each warning once and link to shared recovery guidance where needed.\n\nFor example, explain that selecting a file differs from opening it, that desktop edits require an explicit upload, and that a cancelled transfer can leave partial results. Do not describe standard zoom, scrolling, or text entry.\n\n### Marketing Language\n\nUse confident, benefit-led marketing language on the definition and benefits pages. Make clear promises about what Sambee helps users do, and keep useful comparisons that give readers a familiar product category.\n\nState task-critical requirements where they help the reader, without weakening every benefit with defensive wording. Keep promises grounded in supported capabilities.\n\n### Author and AI Review\n\nApply the content test before adding or expanding user guide content. Before completing a change, remove obvious instructions, duplicate explanations, unnecessary technical detail, and pages that should be short subsections. Preserve confident benefit statements and useful comparisons on the definition and benefits pages. Verify that important limits and recovery actions remain clear. Brevity must not remove information needed to avoid data loss or complete a task safely.\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-shortcodes", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-shortcodes", "title": "Docs Shortcodes", "path": "website-dev-guide/authoring-and-tooling/docs-shortcodes", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.8": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.9": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "1.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "2.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.8": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.9": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "1.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "2.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-editor-tool", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-editor-tool", "title": "Docs Editor Tool", "path": "website-dev-guide/authoring-and-tooling/docs-editor-tool", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 109, "diff_removed": 17}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 37, "diff_removed": 0}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Book\n\nUse this when a book is only a navigation container and should not have a landing page of its own.\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book release-info \\\n  --position start \\\n  --structural-only\n```\n\nThat creates the book directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nInstead:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is a manual content-materialization step, not a page-creation step. The docs editor currently manages page identity and nav structure, but it does not provide a dedicated command that turns an existing inherited page marker into authored page content.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.8": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.9": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "1.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "2.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Book\n\nUse this when a book is only a navigation container and should not have a landing page of its own.\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book release-info \\\n  --position start \\\n  --structural-only\n```\n\nThat creates the book directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nInstead:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is a manual content-materialization step, not a page-creation step. The docs editor currently manages page identity and nav structure, but it does not provide a dedicated command that turns an existing inherited page marker into authored page content.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.8": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.9": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "1.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "2.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-editor-operation-reference", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-editor-operation-reference", "title": "Docs Editor Operation Reference", "path": "website-dev-guide/authoring-and-tooling/docs-editor-operation-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 60, "diff_removed": 4}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 29, "diff_removed": 5}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file. With `--structural-only`, it creates no landing file. `--structural-only` cannot be combined with `--inherit` or `--title`.\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed. It preserves a structural-only book as structural-only; `--title` is not valid when renaming such a book.\n+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen the correct workflow is to materialize real content manually:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis is intentionally outside the scope of `page create`, because the page identity and nav structure already exist.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.8": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.9": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "1.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "2.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n"}, "page_contents": {"0.7": "`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file. With `--structural-only`, it creates no landing file. `--structural-only` cannot be combined with `--inherit` or `--title`.\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed. It preserves a structural-only book as structural-only; `--title` is not valid when renaming such a book.\n+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen the correct workflow is to materialize real content manually:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis is intentionally outside the scope of `page create`, because the page identity and nav structure already exist.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.8": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.9": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "1.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "2.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/site-systems", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "site-systems", "title": "Site Systems", "path": "website-dev-guide/site-systems", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/media-publishing-workflow", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "media-publishing-workflow", "title": "Media Publishing Workflow", "path": "website-dev-guide/site-systems/media-publishing-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.8": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.9": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "1.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "2.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.8": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.9": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "1.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "2.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/typography-system", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "typography-system", "title": "Typography System", "path": "website-dev-guide/site-systems/typography-system", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.8": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.9": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "1.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "2.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n"}, "page_contents": {"0.7": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.8": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.9": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "1.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "2.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/typography-usage-and-boundaries", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "typography-usage-and-boundaries", "title": "Typography Usage And Boundaries", "path": "website-dev-guide/site-systems/typography-usage-and-boundaries", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.8": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.9": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "1.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "2.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.8": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.9": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "1.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "2.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/managed-redirects", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "managed-redirects", "title": "Managed Redirects", "path": "website-dev-guide/site-systems/managed-redirects", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "1.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "2.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "1.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "2.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/setup-and-operations", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "setup-and-operations", "title": "Setup and Operations", "path": "website-dev-guide/setup-and-operations", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing", "parent_id": "section:website-dev-guide/setup-and-operations", "depth": 2, "kind": "page", "label": "set-up-cloudflare-pages-publishing", "title": "Set Up Cloudflare Pages Publishing", "path": "website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.8": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.9": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "1.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "2.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.8": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.9": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "1.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "2.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:release-info", "parent_id": null, "depth": 0, "kind": "book", "label": "release-info", "title": "Release Info", "path": "release-info", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "section:release-info/news-and-changes", "parent_id": "book:release-info", "depth": 1, "kind": "section", "label": "news-and-changes", "title": "News and Changes", "path": "release-info/news-and-changes", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:release-info/news-and-changes/whats-new", "parent_id": "section:release-info/news-and-changes", "depth": 2, "kind": "page", "label": "whats-new", "title": "Whats New", "path": "release-info/news-and-changes/whats-new", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "authored"}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 47, "diff_removed": 46}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 113, "diff_removed": 46}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 186, "diff_removed": 132}}, "content_versions": {"0.8": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar: UX\n\nThe [quick bar](../../../user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar/) is Sambee's main navigation element. It sits in the top bar above the file list and is designed to be the single point of control for directory navigation, file list filtering, and command lookup and execution.\n\nPreviously, those three functions were not clearly distinguished. The three modes are now separated more distinctly, and the current mode is shown directly in the quick bar through a dedicated button. This makes the feature easier to discover and also allows users to switch modes with the mouse or by touch (in addition to the existing keyboard shortcuts).\n\nIn addition, several bugs were fixed to improve the overall experience.\n\n## Companion: More Secure Pairing \u0026 Communication Flows\n\nThis release makes Sambee Companion connections more secure, from the first pairing step through ongoing communication during local-drive access and desktop editing.\n\n**Pairing** is now tracked per Sambee site instead of through one global paired state. Pending approvals can be cancelled cleanly, and the browser now shows clearer states when Companion is unavailable, waiting for local approval, needs repair, or has lost its editing session.\n\nSambee also now trusts only the specific Sambee site you approved, limits what the local Companion service exposes, and uses narrower one-task-at-a-time edit credentials behind the scenes.\n\n**Native editing** is also more resilient. Sambee now uses tighter, task-specific edit permissions, renews long-running edit sessions when needed, and returns you to the browser with a clearer next step if sign-in, lock ownership, or recovery fails, instead of leaving you stuck with a vague error.\n\n## File Opening: Speed \u0026 Flexibility\n\nWhen opening files for previewing or editing, you want quick previews, but you also want the ability to choose which app a file is opened in. Both paths are now efficiently available:\n\nOpen files in Sambee's browser-based viewers:\n\n- Click a file or press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it in Sambee's associated viewer.\n- If no associated viewer exists, or if you press \u003ckbd\u003eShift + Enter\u003c/kbd\u003e, a viewer picker dialog appears.\n   - The picker lets you choose a Sambee browser viewer or a native app.\n\nOpen files in natively installed apps:\n\n- Press \u003ckbd\u003eCtrl + Enter\u003c/kbd\u003e to open a file in its associated native app, or right-click it and select **Open in Native App**.\n- If no associated native app has been chosen, or if you press \u003ckbd\u003eCtrl + Alt + Enter\u003c/kbd\u003e, an app picker dialog appears.\n\n## Markdown Editor: Strategy Change\n\nThe WYSIWYG Markdown editor is gone for a simple reason: UX. There is no open-source rich-text (WYSIWYG) Markdown editor that provides a great user experience. The previous editor was not up to the task.\n\nThe better option is CodeMirror, one of the best available editors, configured for Markdown. It provides a first-rate editing experience and battle-tested add-ons for many of the quality-of-life features people have come to expect from modern editors.\n\n### Interactive Markdown Table Editing\n\nEditing Markdown in a text editor works well for headings and lists, but tables are different. Markdown table syntax is unwieldy, especially when inserting a column in the middle, and the source is difficult to scan. Tables need an interactive WYSIWYG interface that looks and feels like a spreadsheet application. Sambee provides exactly that.\n\n## Text File Viewer and Editor\n\nSince we already have an excellent text editor (see the Markdown Editor note), we might as well put it to good use as a generic text file editor. Sambee can now open, display, and edit any kind of text-based file, with all the bells and whistles of a first-rate editor, for example syntax highlighting.\n\n## Miscellaneous\n\n### Home Screen\n\n- Added a help button next to the settings (gear) icon.\n\n### File List\n\n- Increased the font size on mobile.\n\n### PDF Viewer\n\n- Intra-document links now work correctly, e.g. from a table of contents.\n\n### Under the Hood\n\n- Major dependency upgrades across the board, including React 19 and MUI 9.\n- Improved suspend, resume, and reload resilience.\n\n## Internals\n\n### Documentation System\n\nSambee has a best-in-class documentation system that deduplicates content, inheriting unchanged text copy through versions. This enables us to provide complete and accurate docs for each product version while minimizing maintenance effort.\n\nThis release adds a docs reporting and visualization tool that creates an HTML report of every docs book, section, and page, including its properties, such as whether it is inherited or branched. The report also has a diff view that highlights changes between any two document versions.\n\nDocs editor tool improvements include:\n\n- UI improvements, including better help output.\n- New commands to convert pages between inherited and independent: `page materialize` and `page inherit`.\n- A test and validation suite that also runs in CI.\n", "0.9": "+++\ntitle = \"What's New\"\n+++\n\n## OpenID Connect (OIDC) Authentication and Single Sign-On (SSO)\n\nSingle sign-on was on my list of essential features from the very beginning. Having one source of truth for authentication and authorization is of great benefit even in the smallest networks with single-digit user counts.\n\nSambee includes a secure and comprehensive implementation of OpenID Connect for authentication through IAM servers such as Authelia or Keycloak. If OIDC is configured as the only authentication method, SSO happens behind the scenes and is fully transparent to users who are already logged in to the IAM server. Otherwise, users trying to access Sambee are redirected to the IAM server to authenticate. Once that has happened, they're redirected back to Sambee.\n\nSambee's [OIDC implementation](../../../admin-guide/authentication/openid-connect-authentication-setup/) comes with auto-provisioning, which creates Sambee user accounts automatically after successful OIDC authentication. This can (and often should) be gated by group membership so that only members of a specific group are allowed access to Sambee. Similarly, Sambee's user roles are assigned depending on group membership. This makes it possible to centrally manage access to Sambee's user roles (e.g., admin) in your IAM system.\n\n### Authentication Configuration Change\n\nAuthentication mode is selected only in **Settings** \u003e **Administration** \u003e **Authentication** and defaults to **Password only** for a new installation. The configuration file can only disable enforcement temporarily with `[auth] disable_enforcement = true`; the stored UI mode remains unchanged.\n\nThis is a breaking configuration change. `auth_method` is rejected in both `[auth]` and `[security]`, and existing installations are not migrated automatically. Remove the retired key before upgrading.\n\n## Settings \u0026 Dialogs Overhaul\n\nThe settings got a good UX overhaul that should make them consistent, accessible and, hopefully, much nicer to look at. They're fully responsive, of course, adapting flexibly to phone and desktop screen dimensions. They're also very optimized for efficient keyboard usage while offering touch-friendly sizing on mobile devices.\n\n### New Settings\n\nThe settings also gained several new category pages:\n\n- New personal **Account** settings page\n- New admin **About** settings page\n- New admin **Authentication** settings page\n- New admin **Network** settings page\n- New admin **SMB** settings page\n\nThe about page comes with a feature that may come in handy: creating a **support report** with redacted diagnostic information that's safe to post online.\n\n### User Management Page: Visibility Update\n\nThe user management page in settings was reimplemented to provide significantly better visibility through search, filtering, sorting, summary shortcuts, and a more compact presentation.\n\n### Dialog Look \u0026 Feel\n\nThe refreshed and improved look and feel from settings was applied to the various dialogs that are shown when you copy, move, create, or delete files and/or directories. These dialogs now convey more information in a better way than before.\n\n## Dark Theme Polishing\n\nThe dark theme got a good new coat of paint. The colors of all elements, including backgrounds, text, menus, and dialogs, were tweaked to ensure visual clarity and eye-soothing contrasts.\n\n## Markdown Editor Improvements\n\n- Lists are normalized (formatted) when saved, using `-` for unordered lists and `1.` for every ordered-list item.\n- The editor updates to display the normalized Markdown written to disk after a successful save.\n- Unsaved edits are stored in the browser's local storage so they're not lost when re-authenticating, for example.\n\n## SMB Hardening\n\nTaking a client session isolation bug as a cue, SMB connection handling has been thoroughly hardened. New settings let administrators require Kerberos authentication and SMB 3+ transport encryption. SMBv1 remains disabled and SMB signing is required for every connection.\n\n## Miscellaneous\n\n- **Deleting multiple files** works correctly.\n- The keyboard **shortcuts help** dialog is searchable and resizable.\n\n## Under the Hood\n\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n- Docker container **logging**: severity reclassification\n\n## Internals\n\n### Release Workflow v2: Docker \u0026 Companion Version Lockstep\n\nSambee has a sophisticated build and release system (see the public [docs](../../../developer-guide/release-and-versioning/release-overview/)). Previously, releases and version numbers of the Docker image and the Companion app were deliberately independent. However, it turned out that it's more efficient and natural to increment the versions of both components in sync.\n\nThis led to a significant architectural change that started with a redefinition of the version number ([details](../../../developer-guide/release-and-versioning/product-versioning/)), followed by a second step in which the release processes were reworked to follow a straightforward pattern:\n\n 1. Increment the version number.\n 1. Create a build with that version (Docker image and/or Companion app).\n 1. Promote that build to the `test` channel and test.\n 1. Promote the build to the `beta` and/or `stable` channels.\n\n Crucially, in this new model a build is created only once. Releases happen through promoting existing builds. This guarantees that the version that was tested is exactly what is released later on.\n\n### Docker Dev/Prod Images: Shared Runtime Base Architecture\n\nThe development (devcontainer) and production Docker images are built off a common shared runtime base. This facilitates maintenance and ensures that the shipped image is identical to the environment the developer tested in.\n", "1.0": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar\n\n### File Search\n\nWith the addition of file search (keyboard shortcut: \u003ckbd\u003e/\u003c/kbd\u003e), Sambee's quick bar is becoming a universal search and navigation tool.\n\nFile search complements the existing directory navigation (keyboard shortcut: \u003ckbd\u003eCtrl+K\u003c/kbd\u003e) by providing instant access to recently opened files across directories. File search supersedes file filtering mode, which was removed.\n\n### Directory Navigation History\n\nDirectory navigation now has a history. When you're looking for something, just open the quick bar in directory nav mode and it'll probably already be there. If not, typing a few characters of the name should bring it up in milliseconds.\n\n### Other Changes\n\n- Changed \u003ckbd\u003eF1\u003c/kbd\u003e to consistently invoke keyboard shortcuts help\n\n## Text and Markdown Editors\n\n### Search and Replace\n\nIn any editor, search and replace are essential functions that need to work efficiently while providing granular control. The text and the Markdown editors got just that: compact search and replace popouts with history, regex support and full keyboard usability.\n\n### Other Changes\n\n- Added keyboard shortcuts help\n- Added word wrap (toggled by keyboard shortcut \u003ckbd\u003eAlt+Z\u003c/kbd\u003e)\n- Added viewport scrolling (keyboard shortcut \u003ckbd\u003eCtrl+Arrow up/down\u003c/kbd\u003e)\n- Fixed text selection highlighting\n- Fixed `lock not found or expired` when saving\n\n### Markdown Editor\n\n- Added \u003ckbd\u003eCtrl+B\u003c/kbd\u003e and \u003ckbd\u003eCtrl+I\u003c/kbd\u003e keyboard shortcuts for bold and italic formatting\n\n## PDF Viewer\n\n### More Speed and Higher Fidelity: New Approach to Normalization\n\nEarlier versions normalized every PDF with Ghostscript. This introduced occasional issues and slowed down the viewer. Sambee now opens PDFs in their original form first. When a PDF cannot be displayed because its internal structure is incompatible with the viewer, Sambee can create a separate normalized version for viewing; the original file is never modified. Compatibility processing is limited by file size, processing time, memory, and temporary storage, and each normalized PDF is checked before use.\n\n### Other Changes\n\n- Mobile: swipe to move between pages\n- Encrypted PDFs: the user is now asked to enter a password\n- Large PDFs: better user feedback while loading\n- Color rendering: support for ICC profiles and CMYK\n- Image codecs: support for JPEG 2000 (JXL)\n- Bugfix: geometry changes between pages, e.g., from portrait to landscape, would create endless \"flicker loop\"\n- Bugfix: page rotation commands in the file were not honored\n\n## File List\n\n### ZIP Archive Creation, Inspection, and Extraction\n\nSambee lets you navigate seamlessly into ZIP archives the same way you'd navigate into subdirectories to explore their contents. The UX is instantaneous - only the relevant parts of the ZIP file are decoded. When extracting or compressing, the archive is streamed directly from source to target to minimize CPU, memory, and disk utilization. ZIP operations, like any other, are fully supported across backend boundaries, i.e., between SMB connections and local drives.\n\nThe addition of ZIP archive inspection was the right opportunity to implement storage and content provider abstraction layers. These new abstractions centralize knowledge of storage backends (e.g., SMB, Companion) and how to work with the data on the storage (e.g., regular files, archives), respectively. Introducing these abstractions significantly improves the product's architecture and will greatly simplify adding additional backends or container file types in the future.\n\n### Upload \u0026 Download\n\nA product like Sambee needs efficient ways to get files and folders in and out of the system. To upload files or folders to SMB or local drive destinations, either drag them to Sambee's file browser or select the **Upload** (\u003ckbd\u003eCtrl+U\u003c/kbd\u003e) command in the bottom toolbar. To download files or folders, choose files and/or folders and select the **Download** (\u003ckbd\u003eCtrl+D\u003c/kbd\u003e) command in the bottom toolbar.\n\nDownloading creates a temporary ZIP archive from the selected files and folders, which is then streamed to the browser and subsequently deleted. Sambee allows downloading from all locations: from SMB connections, from local drives, and even from inside ZIP archives.\n\n### Local Drives: Resolve .LNK Files\n\nShortcuts (`.lnk` files), symlinks, and junctions on local drives now show the target path in the status bar. The target information is pulled in asynchronously after the directory list has loaded - we don't want to give up on that snappy UI, after all. Paths are sensibly shortened to fit the available row width.\n\nWhen activated, file targets are opened whereas directory targets are navigated to.\n\n### File Copy and Move: Overwrite Options\n\nCopy and move operations can now overwrite an existing file or replace it only when the source is newer. The same choices work for batches and apply to all supported local and SMB transfers. Directories with the same name are merged safely, preserving destination-only content and resolving only conflicting files.\n\n### Command Toolbar (Desktop) \u0026 Per-Row Actions (Mobile)\n\nA new toolbar at the bottom of the file list makes available commands discoverable. On small screens, typical mobile controls are used instead: a \"+\" icon to create new files or directories and per-row action menus to access commands that operate on individual files or folders.\n\n### Item Selection on Small Screens (Mobile)\n\nOn phones and other small screen devices, files and folders can be selected either through a long press or via the item action menu. Once one item is selected, Sambee switches to multi-selection mode where additional items can be selected through a single tap. An action bar at the bottom of the screen provides access to commands.\n\n### File Metadata on Small Screens (Mobile)\n\nOn phones and other small screen devices, file size and modification time are now displayed in a two-line layout.\n\n### Other Changes\n\n- Added a toolbar button to switch between single-pane and dual-pane modes.\n- When keyboard shortcuts are ignored (because inapplicable in the current situation), Sambee now shows a toast message to make the user unobtrusively aware of the fact.\n- Keyboard navigation: removed delay after entering a new directory.\n- Typeahead buffer: cleared when \u003ckbd\u003eEsc\u003c/kbd\u003e is pressed.\n- The status bar is now always shown.\n\n## Settings\n\n### No More Save Button\n\nClicking a save button at the bottom of the page after adjusting some configuration settings is easily forgotten. So best get rid of that pesky save button altogether. Modern UIs like Sambee's are clever enough to apply config changes automatically and show the user that saving happened through subtle visual cues.\n\n### New Settings\n\nThe settings gained a new category page:\n\n- New admin settings page: **File Search**\n\nFile browser settings:\n\n- **Touch-friendly file selection:** controls how mobile-style file selection is enabled (auto, always on, off).\n\nSystem settings:\n\n- **Temporary archive download size limit:** sets the maximum size of the temporary ZIP archive created when multiple items are downloaded.\n\n### Other Changes\n\n- Localization: Timestamps weren't properly localized in some settings pages (account, user management).\n\n## Image Viewer\n\n- Large images: better user feedback while loading\n\n## Miscellaneous\n\n- Mobile UI: text size increase to improve readability\n- PWA on Chrome on Android: changed the system status bar color from the default blue to gold, matching Sambee's top bar\n- OIDC configuration fields now accept multiple group names as advertised\n- Bugfix: Concurrent OIDC token refreshes would cause SQLite database lock errors.\n- Unicode: file and directory names are normalized to Unicode NFC (single characters) when renamed or created/copied/moved.\n\n## Under the Hood\n\n- Frontend: improved recovery after network unavailability (e.g., after suspend/resume)\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n\n## Internals\n\n### Release Workflow: Companion Alignment with Docker Image\n\nCompanion's release process has been simplified and aligned to match the Docker image workflow:\n\n1. When a new Companion build is created, its GitHub release is published automatically and promoted to the `test` channel.\n1. Interim Companion GitHub releases are deleted automatically when they're no longer needed.\n\n### Other Changes\n\n- Dependency security: The backend's lockfile update process was simplified so that Dependabot can now update lockfiles, too. This removes the need to check out Dependabot PRs locally just to run a lockfile update script.\n", "2.0": "+++\ntitle = \"What's New\"\n+++\n\n## \u26a0\ufe0f Action Required\n\nSambee's GitHub repository was moved to an organization account. This makes it necessary that you update the Docker Compose image URL to `ghcr.io/sambee-app/sambee` in your Docker Compose file (see the [Docker deployment docs](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for details).\n\n## Theme Editor\n\nUI themes are an integral part of an app's visual presentation. As so often, flexibility is key. Some like it dark, others colorful, some require high-contrast, others prefer muted colors.\n\nSambee now has a multi-layer theme system. It differentiates between built-in themes, site-wide themes which only admins can manage, and users' personal themes. Any user can modify existing themes for their own use; admins can also provide themes for other users on the same Sambee server and designate a default theme for new users.\n\nWith Sambee's new theme editor, users can change all theme colors via hex values or the integrated RGBA color picker (which covers transparency in addition to color). Themes can be imported and exported, too.\n\n## File List\n\n### Mouse Selection on Desktop\n\nPrevious versions of Sambee introduced multi-selection for mobile users and keyboard aficionados on desktop. Mouse coverage was lacking. That has been rectified now: Selecting multiple files with a mouse is now straightforward. Click a file or folder icon to select it, then Shift-click another icon to add everything in between without losing your earlier selections. The pane's status bar keeps the count in view.\n\n### New Keyboard Shortcuts\n\n- New tab: \u003ckbd\u003eCtrl+Alt+T\u003c/kbd\u003e opens the current location in a new browser tab.\n- Pane location: \u003ckbd\u003eCtrl+Left\u003c/kbd\u003e sets the left pane to the right pane's location, and \u003ckbd\u003eCtrl+Right\u003c/kbd\u003e sets the right pane to the left pane's location.\n- Item selection: keyboard shortcuts now include \u003ckbd\u003eShift+Home\u003c/kbd\u003e and \u003ckbd\u003eShift+End\u003c/kbd\u003e.\n\n### Other Changes\n\n- Sambee no longer uses \u003ckbd\u003eCtrl+1\u003c/kbd\u003e and \u003ckbd\u003eCtrl+2\u003c/kbd\u003e for pane focus so as not to block these shortcuts for browser tab selection.\n- Native mobile sharing is now available for single or multiple files from the file list.\n- Single-file downloads are now streamed directly without buffering in memory. This speeds up downloads and effectively removes limits imposed by file size.\n\n### Bugfixes\n\n#### File Copy/Move Fixes\n\n- Uploads and copy or move operations no longer interfere with each other's conflict decisions.\n- Moving files between SMB connections no longer leaves the original in place when it should have been deleted.\n- SMB moves now protect the source from concurrent edits and renames, preventing deletion of changes that weren't copied yet.\n- Overwriting an existing SMB file now replaces it atomically instead of failing.\n- Cancelling a move after copying finishes, but before source deletion starts, now correctly reports that both copies were kept.\n- Transfer results now show when a file was copied or replaced, even if removing or checking the original fails.\n- When transferring a folder, a problem with one file no longer hides files already copied, moved, or replaced from the summary.\n- Interrupted SMB moves now release files safely, without leaving them open or interrupting work still in progress.\n- Pressing Enter after a transfer finishes no longer starts the same transfer again.\n- SMB file metadata timezones and ZIP creation now consistently use UTC.\n- SMB connection idle cleanup and failed-request duration logs now use a monotonic clock, so daylight saving time and system clock changes do not affect elapsed-time calculations.\n\n#### SMB Change Monitoring Fixes\n\nFile list:\n\n- File-list monitoring now watches only immediate children, so changes deeper in a folder don't trigger unnecessary refreshes.\n- When changes happen, the file list is now refreshed in the background.\n- File list refreshes are now coalesced and rate-limited.\n\nDirectory cache for instant navigation:\n\n- Quick directory navigation keeps its existing index when a background scan times out or fails.\n- Background scans keep the live directory index when a removal or rename overlaps a read, including when its notification arrives late. This prevents changes from being applied twice when a folder's name is reused.\n- Changing a connection's target or sign-in details no longer reuses directory suggestions from its old configuration.\n- Directory indexing excludes junctions, other reparse descendants, and DFS shares to prevent unsafe traversal.\n- Startup verification and scheduled directory scans now stop cleanly when their cache is removed.\n\n#### Other Fixes\n\n- Invalid file browser URLs no longer break the page or prevent the other pane from loading.\n- Overlapping download requests were allowed.\n- A failed background connection refresh no longer hides a recovered file listing.\n- Renaming a file to a name that differed by case only failed on local drive connections.\n\n## OpenID Connect (OIDC)\n\n### Refresh Token \u0026 `offline_access` Are Now Optional\n\nMany identity providers require the `offline_access` scope to issue refresh tokens, but some (like OneLogin) rejects that scope in the authorization code flow and can issue a refresh token without it when refresh tokens are enabled for the app.\n\nSambee uses a provider refresh token when one is returned, whether or not `offline_access` was requested. If no refresh token is returned, Sambee can continue issuing short-lived API tokens from the browser session for up to 8 hours by default (configurable from 1 to 24 hours). After Sambee's user session expires, the user must sign in through the identity provider again.\n\n### Re-Login Broadcast to Other Open Tabs\n\nWhen an OIDC login is necessary, all Sambee browser tabs switch to the login page. After a successful login in one tab, that tab now broadcasts a login complete hint. When other tabs on the login page receive that hint, they return to their respectice previous URLs.\n\n### Bugfixes\n\n- OIDC login failures after password reset: OIDC login now completes reliably after an administrator resets the account\u2019s password. Sambee ignores responses from the previous browser session while the new login finishes, reloads the user\u2019s themes and settings, and returns to the file browser instead of the login page.\n- Sambee always removed a trailing slash from the issuer URL, which could cause errors with providers like Authentik. Trailing slashes are now left in place.\n\n## Text and Markdown Editors\n\n### Text Viewer and Editor Combined\n\nSambee's text viewer and text editor are now combined into a single component. Text files now open directly in the editor. If write mode cannot be enabled, text editor operates in read-only mode and a notification is shown.\n\nAs part of this change, Sambee got a consistent toast-based notification system for info, warning, and error messages.\n\n### Syntax Highlighting and Rendering Performance Optimization\n\nSambee now uses a consolidated syntax highlighting system throughout all text and Markdown rendering surfaces: text editor, Markdown editor, fenced code blocks in Markdown viewer and Markdown editor. The syntax highlighting system is integrated with the theming system; highlight colors are now part of each theme and can be edited in the new theme editor.\n\nSyntax highlighting is available for a wide range of languages and file types ([docs](../../../user-guide/reference/text-file-support-and-syntax-highlighting/)).\n\nText editor and Markdown editor performance was significantly boosted, especially for long documents. This was achieved through virtualization and viewport rendering.\n\n## Markdown Viewer\n\n### Print and Save as PDF\n\nWhen you print or save as PDF from the browser, the Markdown viewer reformats the full rendered document to fit the page, spanning multiple pages as needed. A new print icon in the top bar makes the new functionality discoverable.\n\n### Other Changes\n\n- Closing the editor by clicking the X now works in the same way as pressing \u003ckbd\u003eEsc\u003c/kbd\u003e: it returns to the viewer. From there, another click returns to the file list.\n- When reloading a browser tab with an editor, Sambee now recovers the file lock. This prevents the error `Unable to enter edit mode. File is locked for editing by \u003cusername\u003e`.\n\n## Quick Bar: Directory Navigation v2\n\nDirectory search and navigation in the quick bar was put on a new foundation:\n\n- Local drives are now indexed, too.\n- The indexing process is now faster and more resilient.\n- The directory index storage was upgraded from JSONL to SQLite databases.\n\n## Miscellaneous\n\n### Native Mobile Sharing\n\nConsolidated the native mobile sharing implementation across the file list and image, PDF, text, and Markdown viewers and editors. When sharing fails, a dialog with details can be invoked to facilitate issue reporting.\n\nText editor and Markdown viewer/editor now have an option to share the current content as text as an alternative to sharing the stored file. This helps circumvent Chrome restrictions that prevent sharing file types such as Markdown.\n\nImage and PDF viewers alway share the displayed content, which may have been normalized for viewing in the browser.\n\n### Full Browser History Navigation\n\nEvery navigation step is now encoded in the URL and recorded in browser history. This enables browser back/forward navigation across the entire Sambee workspace, including the file list, viewers, and editors.\n\n### Local Drive Acess\n\nSambee now checks local-drive access before saying the browser is ready to use Companion. If the check fails, Local Drives settings distinguish between an outdated Companion, an outdated Sambee page, and a pairing that needs to be restored.\n\nWhen Companion rejects a request while browsing a local drive, the file list points to the affected pane and offers a way to reload Sambee or open Local Drives, depending on what went wrong.\n\n### Unencrypted HTTP Support\n\nSambee now deals with unencrypted HTTP explicitly:\n\n- Companion pairing and operations are unavailable.\n- File copying caused a `crypto.randomUUID` error. This has been fixed by implementing a fallback.\n- File uploading would show `outcome uncertain` and not upload files on HTTP/1.1 connections (even over HTTPS). This has been fixed by sending files directly instead of using a streamed request body, so uploads work on HTTP/1.1 while still showing progress.\n- Copying to the clipboard (used in Settings) is now disabled.\n\nHTTP for development on `localhost` is treated as secure by browsers and continues to be supported by Sambee.\n\n### Supported Browser Detection\n\nIf your browser is too old or lacks features Sambee needs, you'll now see a clear message instead of a blank page. The message identifies missing capabilities and links to the browser requirements so you can choose a supported browser.\n\n### Password Login\n\n- When an admin configures a user to require a password change, that change is now enforced upon the next password login.\n- Local usernames are now evaluated case-insensitively.\n- The password field got an option to reveal the password.\n\n### Settings\n\n- User Management: Table column content could overflow into the next row. This was fixes with a comprehensive layout revision.\n\n## Under the Hood\n\n### Security Review\n\nA security review resulted in the following improvements:\n\n- OIDC login now binds the callback and login grant to the browser that started the login flow, preventing a grant from being redeemed in another browser.\n- Only admins can list and download uploaded mobile logs; signed-in users can still upload logs for troubleshooting.\n- Companion requests now use signatures tied to the HTTP method and requested URL, so a signature can't be reused for another request.\n- Mobile log uploads have a size limit, and stored logs are pruned when they exceed the storage budget.\n- HTML, XHTML, and SVG files, including archive members, download instead of running as active content in the viewer.\n\n### Other Changes\n\n- The backend's Python environment was upgraded from 3.13 to 3.14.\n- Fixed the container startup warning: `AuthlibDeprecationWarning: The httpx module is deprecated; please use httpx2 instead.`\n- Reduced the Frontend's JavaScript chunk size.\n\n### Dependency Security\n\n- Updated all dependencies with known issues or vulnerabilities to fixed versions.\n- Pinned all third-party GitHub Actions workflows to commit SHAs.\n- Frontend: removed `patch-package` to get rid of vulnerable transisitve dependency `braces`.\n- Backend: PIP is now upgraded before use and uninstalled from the Docker image afterwards.\n\n### Frontend Type Correctness\n\nType correctness of frontend code and tests is now enforced. As part of this implementation, 1,152 diagnostics across 162 files were fixed: 840 in tests, 311 in application code,\nand one in an imported browser-test helper.\n\n## Internals\n\n- Companion build for Windows: Authenticode signing was removed from PR check builds and only remains on release workflows.\n- GitHub Actions: replaced `pull_request_target` as it will be removed on public repositories by default in November.\n- GitHub Actions: cache retention optimization.\n"}, "page_contents": {"0.8": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar: UX\n\nThe [quick bar](../../../user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar/) is Sambee's main navigation element. It sits in the top bar above the file list and is designed to be the single point of control for directory navigation, file list filtering, and command lookup and execution.\n\nPreviously, those three functions were not clearly distinguished. The three modes are now separated more distinctly, and the current mode is shown directly in the quick bar through a dedicated button. This makes the feature easier to discover and also allows users to switch modes with the mouse or by touch (in addition to the existing keyboard shortcuts).\n\nIn addition, several bugs were fixed to improve the overall experience.\n\n## Companion: More Secure Pairing \u0026 Communication Flows\n\nThis release makes Sambee Companion connections more secure, from the first pairing step through ongoing communication during local-drive access and desktop editing.\n\n**Pairing** is now tracked per Sambee site instead of through one global paired state. Pending approvals can be cancelled cleanly, and the browser now shows clearer states when Companion is unavailable, waiting for local approval, needs repair, or has lost its editing session.\n\nSambee also now trusts only the specific Sambee site you approved, limits what the local Companion service exposes, and uses narrower one-task-at-a-time edit credentials behind the scenes.\n\n**Native editing** is also more resilient. Sambee now uses tighter, task-specific edit permissions, renews long-running edit sessions when needed, and returns you to the browser with a clearer next step if sign-in, lock ownership, or recovery fails, instead of leaving you stuck with a vague error.\n\n## File Opening: Speed \u0026 Flexibility\n\nWhen opening files for previewing or editing, you want quick previews, but you also want the ability to choose which app a file is opened in. Both paths are now efficiently available:\n\nOpen files in Sambee's browser-based viewers:\n\n- Click a file or press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it in Sambee's associated viewer.\n- If no associated viewer exists, or if you press \u003ckbd\u003eShift + Enter\u003c/kbd\u003e, a viewer picker dialog appears.\n   - The picker lets you choose a Sambee browser viewer or a native app.\n\nOpen files in natively installed apps:\n\n- Press \u003ckbd\u003eCtrl + Enter\u003c/kbd\u003e to open a file in its associated native app, or right-click it and select **Open in Native App**.\n- If no associated native app has been chosen, or if you press \u003ckbd\u003eCtrl + Alt + Enter\u003c/kbd\u003e, an app picker dialog appears.\n\n## Markdown Editor: Strategy Change\n\nThe WYSIWYG Markdown editor is gone for a simple reason: UX. There is no open-source rich-text (WYSIWYG) Markdown editor that provides a great user experience. The previous editor was not up to the task.\n\nThe better option is CodeMirror, one of the best available editors, configured for Markdown. It provides a first-rate editing experience and battle-tested add-ons for many of the quality-of-life features people have come to expect from modern editors.\n\n### Interactive Markdown Table Editing\n\nEditing Markdown in a text editor works well for headings and lists, but tables are different. Markdown table syntax is unwieldy, especially when inserting a column in the middle, and the source is difficult to scan. Tables need an interactive WYSIWYG interface that looks and feels like a spreadsheet application. Sambee provides exactly that.\n\n## Text File Viewer and Editor\n\nSince we already have an excellent text editor (see the Markdown Editor note), we might as well put it to good use as a generic text file editor. Sambee can now open, display, and edit any kind of text-based file, with all the bells and whistles of a first-rate editor, for example syntax highlighting.\n\n## Miscellaneous\n\n### Home Screen\n\n- Added a help button next to the settings (gear) icon.\n\n### File List\n\n- Increased the font size on mobile.\n\n### PDF Viewer\n\n- Intra-document links now work correctly, e.g. from a table of contents.\n\n### Under the Hood\n\n- Major dependency upgrades across the board, including React 19 and MUI 9.\n- Improved suspend, resume, and reload resilience.\n\n## Internals\n\n### Documentation System\n\nSambee has a best-in-class documentation system that deduplicates content, inheriting unchanged text copy through versions. This enables us to provide complete and accurate docs for each product version while minimizing maintenance effort.\n\nThis release adds a docs reporting and visualization tool that creates an HTML report of every docs book, section, and page, including its properties, such as whether it is inherited or branched. The report also has a diff view that highlights changes between any two document versions.\n\nDocs editor tool improvements include:\n\n- UI improvements, including better help output.\n- New commands to convert pages between inherited and independent: `page materialize` and `page inherit`.\n- A test and validation suite that also runs in CI.\n", "0.9": "+++\ntitle = \"What's New\"\n+++\n\n## OpenID Connect (OIDC) Authentication and Single Sign-On (SSO)\n\nSingle sign-on was on my list of essential features from the very beginning. Having one source of truth for authentication and authorization is of great benefit even in the smallest networks with single-digit user counts.\n\nSambee includes a secure and comprehensive implementation of OpenID Connect for authentication through IAM servers such as Authelia or Keycloak. If OIDC is configured as the only authentication method, SSO happens behind the scenes and is fully transparent to users who are already logged in to the IAM server. Otherwise, users trying to access Sambee are redirected to the IAM server to authenticate. Once that has happened, they're redirected back to Sambee.\n\nSambee's [OIDC implementation](../../../admin-guide/authentication/openid-connect-authentication-setup/) comes with auto-provisioning, which creates Sambee user accounts automatically after successful OIDC authentication. This can (and often should) be gated by group membership so that only members of a specific group are allowed access to Sambee. Similarly, Sambee's user roles are assigned depending on group membership. This makes it possible to centrally manage access to Sambee's user roles (e.g., admin) in your IAM system.\n\n### Authentication Configuration Change\n\nAuthentication mode is selected only in **Settings** \u003e **Administration** \u003e **Authentication** and defaults to **Password only** for a new installation. The configuration file can only disable enforcement temporarily with `[auth] disable_enforcement = true`; the stored UI mode remains unchanged.\n\nThis is a breaking configuration change. `auth_method` is rejected in both `[auth]` and `[security]`, and existing installations are not migrated automatically. Remove the retired key before upgrading.\n\n## Settings \u0026 Dialogs Overhaul\n\nThe settings got a good UX overhaul that should make them consistent, accessible and, hopefully, much nicer to look at. They're fully responsive, of course, adapting flexibly to phone and desktop screen dimensions. They're also very optimized for efficient keyboard usage while offering touch-friendly sizing on mobile devices.\n\n### New Settings\n\nThe settings also gained several new category pages:\n\n- New personal **Account** settings page\n- New admin **About** settings page\n- New admin **Authentication** settings page\n- New admin **Network** settings page\n- New admin **SMB** settings page\n\nThe about page comes with a feature that may come in handy: creating a **support report** with redacted diagnostic information that's safe to post online.\n\n### User Management Page: Visibility Update\n\nThe user management page in settings was reimplemented to provide significantly better visibility through search, filtering, sorting, summary shortcuts, and a more compact presentation.\n\n### Dialog Look \u0026 Feel\n\nThe refreshed and improved look and feel from settings was applied to the various dialogs that are shown when you copy, move, create, or delete files and/or directories. These dialogs now convey more information in a better way than before.\n\n## Dark Theme Polishing\n\nThe dark theme got a good new coat of paint. The colors of all elements, including backgrounds, text, menus, and dialogs, were tweaked to ensure visual clarity and eye-soothing contrasts.\n\n## Markdown Editor Improvements\n\n- Lists are normalized (formatted) when saved, using `-` for unordered lists and `1.` for every ordered-list item.\n- The editor updates to display the normalized Markdown written to disk after a successful save.\n- Unsaved edits are stored in the browser's local storage so they're not lost when re-authenticating, for example.\n\n## SMB Hardening\n\nTaking a client session isolation bug as a cue, SMB connection handling has been thoroughly hardened. New settings let administrators require Kerberos authentication and SMB 3+ transport encryption. SMBv1 remains disabled and SMB signing is required for every connection.\n\n## Miscellaneous\n\n- **Deleting multiple files** works correctly.\n- The keyboard **shortcuts help** dialog is searchable and resizable.\n\n## Under the Hood\n\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n- Docker container **logging**: severity reclassification\n\n## Internals\n\n### Release Workflow v2: Docker \u0026 Companion Version Lockstep\n\nSambee has a sophisticated build and release system (see the public [docs](../../../developer-guide/release-and-versioning/release-overview/)). Previously, releases and version numbers of the Docker image and the Companion app were deliberately independent. However, it turned out that it's more efficient and natural to increment the versions of both components in sync.\n\nThis led to a significant architectural change that started with a redefinition of the version number ([details](../../../developer-guide/release-and-versioning/product-versioning/)), followed by a second step in which the release processes were reworked to follow a straightforward pattern:\n\n 1. Increment the version number.\n 1. Create a build with that version (Docker image and/or Companion app).\n 1. Promote that build to the `test` channel and test.\n 1. Promote the build to the `beta` and/or `stable` channels.\n\n Crucially, in this new model a build is created only once. Releases happen through promoting existing builds. This guarantees that the version that was tested is exactly what is released later on.\n\n### Docker Dev/Prod Images: Shared Runtime Base Architecture\n\nThe development (devcontainer) and production Docker images are built off a common shared runtime base. This facilitates maintenance and ensures that the shipped image is identical to the environment the developer tested in.\n", "1.0": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar\n\n### File Search\n\nWith the addition of file search (keyboard shortcut: \u003ckbd\u003e/\u003c/kbd\u003e), Sambee's quick bar is becoming a universal search and navigation tool.\n\nFile search complements the existing directory navigation (keyboard shortcut: \u003ckbd\u003eCtrl+K\u003c/kbd\u003e) by providing instant access to recently opened files across directories. File search supersedes file filtering mode, which was removed.\n\n### Directory Navigation History\n\nDirectory navigation now has a history. When you're looking for something, just open the quick bar in directory nav mode and it'll probably already be there. If not, typing a few characters of the name should bring it up in milliseconds.\n\n### Other Changes\n\n- Changed \u003ckbd\u003eF1\u003c/kbd\u003e to consistently invoke keyboard shortcuts help\n\n## Text and Markdown Editors\n\n### Search and Replace\n\nIn any editor, search and replace are essential functions that need to work efficiently while providing granular control. The text and the Markdown editors got just that: compact search and replace popouts with history, regex support and full keyboard usability.\n\n### Other Changes\n\n- Added keyboard shortcuts help\n- Added word wrap (toggled by keyboard shortcut \u003ckbd\u003eAlt+Z\u003c/kbd\u003e)\n- Added viewport scrolling (keyboard shortcut \u003ckbd\u003eCtrl+Arrow up/down\u003c/kbd\u003e)\n- Fixed text selection highlighting\n- Fixed `lock not found or expired` when saving\n\n### Markdown Editor\n\n- Added \u003ckbd\u003eCtrl+B\u003c/kbd\u003e and \u003ckbd\u003eCtrl+I\u003c/kbd\u003e keyboard shortcuts for bold and italic formatting\n\n## PDF Viewer\n\n### More Speed and Higher Fidelity: New Approach to Normalization\n\nEarlier versions normalized every PDF with Ghostscript. This introduced occasional issues and slowed down the viewer. Sambee now opens PDFs in their original form first. When a PDF cannot be displayed because its internal structure is incompatible with the viewer, Sambee can create a separate normalized version for viewing; the original file is never modified. Compatibility processing is limited by file size, processing time, memory, and temporary storage, and each normalized PDF is checked before use.\n\n### Other Changes\n\n- Mobile: swipe to move between pages\n- Encrypted PDFs: the user is now asked to enter a password\n- Large PDFs: better user feedback while loading\n- Color rendering: support for ICC profiles and CMYK\n- Image codecs: support for JPEG 2000 (JXL)\n- Bugfix: geometry changes between pages, e.g., from portrait to landscape, would create endless \"flicker loop\"\n- Bugfix: page rotation commands in the file were not honored\n\n## File List\n\n### ZIP Archive Creation, Inspection, and Extraction\n\nSambee lets you navigate seamlessly into ZIP archives the same way you'd navigate into subdirectories to explore their contents. The UX is instantaneous - only the relevant parts of the ZIP file are decoded. When extracting or compressing, the archive is streamed directly from source to target to minimize CPU, memory, and disk utilization. ZIP operations, like any other, are fully supported across backend boundaries, i.e., between SMB connections and local drives.\n\nThe addition of ZIP archive inspection was the right opportunity to implement storage and content provider abstraction layers. These new abstractions centralize knowledge of storage backends (e.g., SMB, Companion) and how to work with the data on the storage (e.g., regular files, archives), respectively. Introducing these abstractions significantly improves the product's architecture and will greatly simplify adding additional backends or container file types in the future.\n\n### Upload \u0026 Download\n\nA product like Sambee needs efficient ways to get files and folders in and out of the system. To upload files or folders to SMB or local drive destinations, either drag them to Sambee's file browser or select the **Upload** (\u003ckbd\u003eCtrl+U\u003c/kbd\u003e) command in the bottom toolbar. To download files or folders, choose files and/or folders and select the **Download** (\u003ckbd\u003eCtrl+D\u003c/kbd\u003e) command in the bottom toolbar.\n\nDownloading creates a temporary ZIP archive from the selected files and folders, which is then streamed to the browser and subsequently deleted. Sambee allows downloading from all locations: from SMB connections, from local drives, and even from inside ZIP archives.\n\n### Local Drives: Resolve .LNK Files\n\nShortcuts (`.lnk` files), symlinks, and junctions on local drives now show the target path in the status bar. The target information is pulled in asynchronously after the directory list has loaded - we don't want to give up on that snappy UI, after all. Paths are sensibly shortened to fit the available row width.\n\nWhen activated, file targets are opened whereas directory targets are navigated to.\n\n### File Copy and Move: Overwrite Options\n\nCopy and move operations can now overwrite an existing file or replace it only when the source is newer. The same choices work for batches and apply to all supported local and SMB transfers. Directories with the same name are merged safely, preserving destination-only content and resolving only conflicting files.\n\n### Command Toolbar (Desktop) \u0026 Per-Row Actions (Mobile)\n\nA new toolbar at the bottom of the file list makes available commands discoverable. On small screens, typical mobile controls are used instead: a \"+\" icon to create new files or directories and per-row action menus to access commands that operate on individual files or folders.\n\n### Item Selection on Small Screens (Mobile)\n\nOn phones and other small screen devices, files and folders can be selected either through a long press or via the item action menu. Once one item is selected, Sambee switches to multi-selection mode where additional items can be selected through a single tap. An action bar at the bottom of the screen provides access to commands.\n\n### File Metadata on Small Screens (Mobile)\n\nOn phones and other small screen devices, file size and modification time are now displayed in a two-line layout.\n\n### Other Changes\n\n- Added a toolbar button to switch between single-pane and dual-pane modes.\n- When keyboard shortcuts are ignored (because inapplicable in the current situation), Sambee now shows a toast message to make the user unobtrusively aware of the fact.\n- Keyboard navigation: removed delay after entering a new directory.\n- Typeahead buffer: cleared when \u003ckbd\u003eEsc\u003c/kbd\u003e is pressed.\n- The status bar is now always shown.\n\n## Settings\n\n### No More Save Button\n\nClicking a save button at the bottom of the page after adjusting some configuration settings is easily forgotten. So best get rid of that pesky save button altogether. Modern UIs like Sambee's are clever enough to apply config changes automatically and show the user that saving happened through subtle visual cues.\n\n### New Settings\n\nThe settings gained a new category page:\n\n- New admin settings page: **File Search**\n\nFile browser settings:\n\n- **Touch-friendly file selection:** controls how mobile-style file selection is enabled (auto, always on, off).\n\nSystem settings:\n\n- **Temporary archive download size limit:** sets the maximum size of the temporary ZIP archive created when multiple items are downloaded.\n\n### Other Changes\n\n- Localization: Timestamps weren't properly localized in some settings pages (account, user management).\n\n## Image Viewer\n\n- Large images: better user feedback while loading\n\n## Miscellaneous\n\n- Mobile UI: text size increase to improve readability\n- PWA on Chrome on Android: changed the system status bar color from the default blue to gold, matching Sambee's top bar\n- OIDC configuration fields now accept multiple group names as advertised\n- Bugfix: Concurrent OIDC token refreshes would cause SQLite database lock errors.\n- Unicode: file and directory names are normalized to Unicode NFC (single characters) when renamed or created/copied/moved.\n\n## Under the Hood\n\n- Frontend: improved recovery after network unavailability (e.g., after suspend/resume)\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n\n## Internals\n\n### Release Workflow: Companion Alignment with Docker Image\n\nCompanion's release process has been simplified and aligned to match the Docker image workflow:\n\n1. When a new Companion build is created, its GitHub release is published automatically and promoted to the `test` channel.\n1. Interim Companion GitHub releases are deleted automatically when they're no longer needed.\n\n### Other Changes\n\n- Dependency security: The backend's lockfile update process was simplified so that Dependabot can now update lockfiles, too. This removes the need to check out Dependabot PRs locally just to run a lockfile update script.\n", "2.0": "+++\ntitle = \"What's New\"\n+++\n\n## \u26a0\ufe0f Action Required\n\nSambee's GitHub repository was moved to an organization account. This makes it necessary that you update the Docker Compose image URL to `ghcr.io/sambee-app/sambee` in your Docker Compose file (see the [Docker deployment docs](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for details).\n\n## Theme Editor\n\nUI themes are an integral part of an app's visual presentation. As so often, flexibility is key. Some like it dark, others colorful, some require high-contrast, others prefer muted colors.\n\nSambee now has a multi-layer theme system. It differentiates between built-in themes, site-wide themes which only admins can manage, and users' personal themes. Any user can modify existing themes for their own use; admins can also provide themes for other users on the same Sambee server and designate a default theme for new users.\n\nWith Sambee's new theme editor, users can change all theme colors via hex values or the integrated RGBA color picker (which covers transparency in addition to color). Themes can be imported and exported, too.\n\n## File List\n\n### Mouse Selection on Desktop\n\nPrevious versions of Sambee introduced multi-selection for mobile users and keyboard aficionados on desktop. Mouse coverage was lacking. That has been rectified now: Selecting multiple files with a mouse is now straightforward. Click a file or folder icon to select it, then Shift-click another icon to add everything in between without losing your earlier selections. The pane's status bar keeps the count in view.\n\n### New Keyboard Shortcuts\n\n- New tab: \u003ckbd\u003eCtrl+Alt+T\u003c/kbd\u003e opens the current location in a new browser tab.\n- Pane location: \u003ckbd\u003eCtrl+Left\u003c/kbd\u003e sets the left pane to the right pane's location, and \u003ckbd\u003eCtrl+Right\u003c/kbd\u003e sets the right pane to the left pane's location.\n- Item selection: keyboard shortcuts now include \u003ckbd\u003eShift+Home\u003c/kbd\u003e and \u003ckbd\u003eShift+End\u003c/kbd\u003e.\n\n### Other Changes\n\n- Sambee no longer uses \u003ckbd\u003eCtrl+1\u003c/kbd\u003e and \u003ckbd\u003eCtrl+2\u003c/kbd\u003e for pane focus so as not to block these shortcuts for browser tab selection.\n- Native mobile sharing is now available for single or multiple files from the file list.\n- Single-file downloads are now streamed directly without buffering in memory. This speeds up downloads and effectively removes limits imposed by file size.\n\n### Bugfixes\n\n#### File Copy/Move Fixes\n\n- Uploads and copy or move operations no longer interfere with each other's conflict decisions.\n- Moving files between SMB connections no longer leaves the original in place when it should have been deleted.\n- SMB moves now protect the source from concurrent edits and renames, preventing deletion of changes that weren't copied yet.\n- Overwriting an existing SMB file now replaces it atomically instead of failing.\n- Cancelling a move after copying finishes, but before source deletion starts, now correctly reports that both copies were kept.\n- Transfer results now show when a file was copied or replaced, even if removing or checking the original fails.\n- When transferring a folder, a problem with one file no longer hides files already copied, moved, or replaced from the summary.\n- Interrupted SMB moves now release files safely, without leaving them open or interrupting work still in progress.\n- Pressing Enter after a transfer finishes no longer starts the same transfer again.\n- SMB file metadata timezones and ZIP creation now consistently use UTC.\n- SMB connection idle cleanup and failed-request duration logs now use a monotonic clock, so daylight saving time and system clock changes do not affect elapsed-time calculations.\n\n#### SMB Change Monitoring Fixes\n\nFile list:\n\n- File-list monitoring now watches only immediate children, so changes deeper in a folder don't trigger unnecessary refreshes.\n- When changes happen, the file list is now refreshed in the background.\n- File list refreshes are now coalesced and rate-limited.\n\nDirectory cache for instant navigation:\n\n- Quick directory navigation keeps its existing index when a background scan times out or fails.\n- Background scans keep the live directory index when a removal or rename overlaps a read, including when its notification arrives late. This prevents changes from being applied twice when a folder's name is reused.\n- Changing a connection's target or sign-in details no longer reuses directory suggestions from its old configuration.\n- Directory indexing excludes junctions, other reparse descendants, and DFS shares to prevent unsafe traversal.\n- Startup verification and scheduled directory scans now stop cleanly when their cache is removed.\n\n#### Other Fixes\n\n- Invalid file browser URLs no longer break the page or prevent the other pane from loading.\n- Overlapping download requests were allowed.\n- A failed background connection refresh no longer hides a recovered file listing.\n- Renaming a file to a name that differed by case only failed on local drive connections.\n\n## OpenID Connect (OIDC)\n\n### Refresh Token \u0026 `offline_access` Are Now Optional\n\nMany identity providers require the `offline_access` scope to issue refresh tokens, but some (like OneLogin) rejects that scope in the authorization code flow and can issue a refresh token without it when refresh tokens are enabled for the app.\n\nSambee uses a provider refresh token when one is returned, whether or not `offline_access` was requested. If no refresh token is returned, Sambee can continue issuing short-lived API tokens from the browser session for up to 8 hours by default (configurable from 1 to 24 hours). After Sambee's user session expires, the user must sign in through the identity provider again.\n\n### Re-Login Broadcast to Other Open Tabs\n\nWhen an OIDC login is necessary, all Sambee browser tabs switch to the login page. After a successful login in one tab, that tab now broadcasts a login complete hint. When other tabs on the login page receive that hint, they return to their respectice previous URLs.\n\n### Bugfixes\n\n- OIDC login failures after password reset: OIDC login now completes reliably after an administrator resets the account\u2019s password. Sambee ignores responses from the previous browser session while the new login finishes, reloads the user\u2019s themes and settings, and returns to the file browser instead of the login page.\n- Sambee always removed a trailing slash from the issuer URL, which could cause errors with providers like Authentik. Trailing slashes are now left in place.\n\n## Text and Markdown Editors\n\n### Text Viewer and Editor Combined\n\nSambee's text viewer and text editor are now combined into a single component. Text files now open directly in the editor. If write mode cannot be enabled, text editor operates in read-only mode and a notification is shown.\n\nAs part of this change, Sambee got a consistent toast-based notification system for info, warning, and error messages.\n\n### Syntax Highlighting and Rendering Performance Optimization\n\nSambee now uses a consolidated syntax highlighting system throughout all text and Markdown rendering surfaces: text editor, Markdown editor, fenced code blocks in Markdown viewer and Markdown editor. The syntax highlighting system is integrated with the theming system; highlight colors are now part of each theme and can be edited in the new theme editor.\n\nSyntax highlighting is available for a wide range of languages and file types ([docs](../../../user-guide/reference/text-file-support-and-syntax-highlighting/)).\n\nText editor and Markdown editor performance was significantly boosted, especially for long documents. This was achieved through virtualization and viewport rendering.\n\n## Markdown Viewer\n\n### Print and Save as PDF\n\nWhen you print or save as PDF from the browser, the Markdown viewer reformats the full rendered document to fit the page, spanning multiple pages as needed. A new print icon in the top bar makes the new functionality discoverable.\n\n### Other Changes\n\n- Closing the editor by clicking the X now works in the same way as pressing \u003ckbd\u003eEsc\u003c/kbd\u003e: it returns to the viewer. From there, another click returns to the file list.\n- When reloading a browser tab with an editor, Sambee now recovers the file lock. This prevents the error `Unable to enter edit mode. File is locked for editing by \u003cusername\u003e`.\n\n## Quick Bar: Directory Navigation v2\n\nDirectory search and navigation in the quick bar was put on a new foundation:\n\n- Local drives are now indexed, too.\n- The indexing process is now faster and more resilient.\n- The directory index storage was upgraded from JSONL to SQLite databases.\n\n## Miscellaneous\n\n### Native Mobile Sharing\n\nConsolidated the native mobile sharing implementation across the file list and image, PDF, text, and Markdown viewers and editors. When sharing fails, a dialog with details can be invoked to facilitate issue reporting.\n\nText editor and Markdown viewer/editor now have an option to share the current content as text as an alternative to sharing the stored file. This helps circumvent Chrome restrictions that prevent sharing file types such as Markdown.\n\nImage and PDF viewers alway share the displayed content, which may have been normalized for viewing in the browser.\n\n### Full Browser History Navigation\n\nEvery navigation step is now encoded in the URL and recorded in browser history. This enables browser back/forward navigation across the entire Sambee workspace, including the file list, viewers, and editors.\n\n### Local Drive Acess\n\nSambee now checks local-drive access before saying the browser is ready to use Companion. If the check fails, Local Drives settings distinguish between an outdated Companion, an outdated Sambee page, and a pairing that needs to be restored.\n\nWhen Companion rejects a request while browsing a local drive, the file list points to the affected pane and offers a way to reload Sambee or open Local Drives, depending on what went wrong.\n\n### Unencrypted HTTP Support\n\nSambee now deals with unencrypted HTTP explicitly:\n\n- Companion pairing and operations are unavailable.\n- File copying caused a `crypto.randomUUID` error. This has been fixed by implementing a fallback.\n- File uploading would show `outcome uncertain` and not upload files on HTTP/1.1 connections (even over HTTPS). This has been fixed by sending files directly instead of using a streamed request body, so uploads work on HTTP/1.1 while still showing progress.\n- Copying to the clipboard (used in Settings) is now disabled.\n\nHTTP for development on `localhost` is treated as secure by browsers and continues to be supported by Sambee.\n\n### Supported Browser Detection\n\nIf your browser is too old or lacks features Sambee needs, you'll now see a clear message instead of a blank page. The message identifies missing capabilities and links to the browser requirements so you can choose a supported browser.\n\n### Password Login\n\n- When an admin configures a user to require a password change, that change is now enforced upon the next password login.\n- Local usernames are now evaluated case-insensitively.\n- The password field got an option to reveal the password.\n\n### Settings\n\n- User Management: Table column content could overflow into the next row. This was fixes with a comprehensive layout revision.\n\n## Under the Hood\n\n### Security Review\n\nA security review resulted in the following improvements:\n\n- OIDC login now binds the callback and login grant to the browser that started the login flow, preventing a grant from being redeemed in another browser.\n- Only admins can list and download uploaded mobile logs; signed-in users can still upload logs for troubleshooting.\n- Companion requests now use signatures tied to the HTTP method and requested URL, so a signature can't be reused for another request.\n- Mobile log uploads have a size limit, and stored logs are pruned when they exceed the storage budget.\n- HTML, XHTML, and SVG files, including archive members, download instead of running as active content in the viewer.\n\n### Other Changes\n\n- The backend's Python environment was upgraded from 3.13 to 3.14.\n- Fixed the container startup warning: `AuthlibDeprecationWarning: The httpx module is deprecated; please use httpx2 instead.`\n- Reduced the Frontend's JavaScript chunk size.\n\n### Dependency Security\n\n- Updated all dependencies with known issues or vulnerabilities to fixed versions.\n- Pinned all third-party GitHub Actions workflows to commit SHAs.\n- Frontend: removed `patch-package` to get rid of vulnerable transisitve dependency `braces`.\n- Backend: PIP is now upgraded before use and uninstalled from the Docker image afterwards.\n\n### Frontend Type Correctness\n\nType correctness of frontend code and tests is now enforced. As part of this implementation, 1,152 diagnostics across 162 files were fixed: 840 in tests, 311 in application code,\nand one in an imported browser-test helper.\n\n## Internals\n\n- Companion build for Windows: Authenticode signing was removed from PR check builds and only remains on release workflows.\n- GitHub Actions: replaced `pull_request_target` as it will be removed on public repositories by default in November.\n- GitHub Actions: cache retention optimization.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:release-info/system-requirements", "parent_id": "book:release-info", "depth": 1, "kind": "section", "label": "system-requirements", "title": "System Requirements", "path": "release-info/system-requirements", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:release-info/system-requirements/requirements", "parent_id": "section:release-info/system-requirements", "depth": 2, "kind": "page", "label": "requirements", "title": "Requirements", "path": "release-info/system-requirements/requirements", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 4, "diff_removed": 2}}, "content_versions": {"1.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivatives)\n- Mozilla Firefox\n- Apple Safari\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is available for Windows 11 on x64.\n", "2.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivates)\n- Mozilla Firefox\n- Apple Safari\n\nModern browser technologies such as web workers are required. If a browser lacks this or another required capability, Sambee shows a browser compatibility message instead of loading the app.\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is currently available for Windows 11 on x64.\n"}, "page_contents": {"1.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivatives)\n- Mozilla Firefox\n- Apple Safari\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is available for Windows 11 on x64.\n", "2.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivates)\n- Mozilla Firefox\n- Apple Safari\n\nModern browser technologies such as web workers are required. If a browser lacks this or another required capability, Sambee shows a browser compatibility message instead of loading the app.\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is currently available for Windows 11 on x64.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}]}</script>
   <script>
     const report = JSON.parse(document.getElementById('report-data').textContent);
     const versions = report.versions;
diff --git a/website/content/docs/2.0/developer-guide/backend-architecture/smb-change-notification-and-directory-freshness/index.md b/website/content/docs/2.0/developer-guide/backend-architecture/smb-change-notification-and-directory-freshness/index.md
index ff89ab90..e72a0086 100644
--- a/website/content/docs/2.0/developer-guide/backend-architecture/smb-change-notification-and-directory-freshness/index.md
+++ b/website/content/docs/2.0/developer-guide/backend-architecture/smb-change-notification-and-directory-freshness/index.md
@@ -157,6 +157,8 @@ Directory rows have a nullable `parent_id` and the `directories_parent(generatio
 
 Item issue counts belong to the producer's observation token. Full passes buffer these counts until the completed parent snapshot commits; reconciliation commits them with the final parent snapshot. Early incomplete child batches retain the pending counts. A stale token discards them and leaves its parent pending. Counts aggregate by issue code in the parent transaction, so coverage, revision, directory changes, and parent completion roll back together if a write fails. Buffered issue payloads count toward the group byte bound.
 
+Both source managers retain a process-local sample of affected parent paths and issue codes after successful parent commits. The sample uses the shared `max_logged_scan_issues_per_pass` bound, removes resolved parent entries after clean reads, and resets for a new full pass. Successful delete observations and parent snapshots also remove samples for deleted subtrees; failed database writes retain the samples. It is not persisted or added to the index schema. Ordinary search responses expose `issue_details_available`; `include_issue_details=true` additionally returns `issue_details` and `issue_details_incomplete`. These details use the same source authorization as directory search. A listed parent can identify a location containing an unreadable child name rather than an unreadable parent itself.
+
 The selected generation records `scan_pass_id` and `scan_active`. A fresh verification resets its queue completion flags and starts a new pass; an interrupted active pass resumes without that reset. A completed pass keeps the selected generation ID. The clean-shutdown marker is cleared on open and set only after a clean, transaction-free close with ready search tokens. A clean reopen skips SQLite `quick_check` and the FTS integrity command when the FTS schema is intact. An unclean reopen runs both checks. Schema, foreign-key, generation, and storage-binding validation still run on every open. Reopen retains valid streamed snapshot names; the first restarted batch replaces them. Invalid names or snapshots owned by completed parents trigger disposable-cache recovery.
 
 Both stores use WAL and `synchronous=NORMAL`. The index is a verified cache, not the source of directory data. A power failure can lose recent cache commits; interrupted or uncommitted work remains pending for verification. Writes, checkpoints, maintenance, and close are serialized through the writer. Queries use read-only connections and explicit transactions. Both runtimes reuse isolated read connections and check their storage binding before each query. Query cancellation handlers are cleared before reuse. Storage leases remain held until admitted readers and workers finish; active database families cannot be evicted.
@@ -167,6 +169,8 @@ Reconciliation uses the same adaptive groups as full passes without advancing th
 
 Empty-query status uses committed metadata snapshots in memory. It does not open SQLite connections or run a directory query. The optional `scan_progress` response contains the phase, completed and queued parent counts, directory count, and start timestamp. Each group commit refreshes progress. The frontend shows active build or update progress before uncertain coverage.
 
+The `cache_state` value `opening` identifies index initialization before scanning. The quick bar hides this status but continues polling. Errors and recovery messages remain visible. Once scanning starts, build or update progress replaces the opening state. A build shows `Indexing...` until its directory count is positive; zero is not shown as a directory result.
+
 Storage must be private and local. Opens and cleanup validate directory ownership, file identity, and aliases. Do not write to managed databases externally or weaken these checks to permit a path-only fallback.
 
 ### Resource Controls
diff --git a/website/content/docs/2.0/developer-guide/frontend-architecture/file-browser-and-navigation-model/index.md b/website/content/docs/2.0/developer-guide/frontend-architecture/file-browser-and-navigation-model/index.md
index 308c8c52..cb860dc4 100644
--- a/website/content/docs/2.0/developer-guide/frontend-architecture/file-browser-and-navigation-model/index.md
+++ b/website/content/docs/2.0/developer-guide/frontend-architecture/file-browser-and-navigation-model/index.md
@@ -96,6 +96,8 @@ Publish usable history and loaded-file results without waiting for index request
 
 Treat incomplete coverage separately from request failure. Background refresh requires `search_contract_version: 1` and must stop when the query, source, visibility, or search session changes, or on terminal failure. See [Directory-Index Consistency](../../backend-architecture/smb-change-notification-and-directory-freshness/#directory-index-consistency) for storage and freshness rules.
 
+Status messages include the connection name. A status becomes a mouse/touch-only link only when it has additional information; do not add an icon or a keyboard tab stop. `SearchStatusDialog` uses `ResponsiveDialogShell`, retains the query and selected result, and returns focus to the quick bar when closed. Source changes close the dialog and cancel its details request. Directory details load on demand through `include_issue_details`; specific request errors use the already received message. Messages without extra information remain plain text.
+
 ## URL-Driven Workspace Navigation
 
 The URL selects the directory, pane layout, viewer, editing intent, and settings view. The file browser stays mounted under overlays. Loaded content, drafts, locks, selection, scroll, search panels, and zoom remain runtime state.
diff --git a/website/content/docs/2.0/user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar/index.md b/website/content/docs/2.0/user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar/index.md
index 9e816fb5..67ae2119 100644
--- a/website/content/docs/2.0/user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar/index.md
+++ b/website/content/docs/2.0/user-guide/find-and-browse-files/smart-navigation-and-the-quick-bar/index.md
@@ -16,6 +16,10 @@ Press <kbd>Ctrl</kbd> + <kbd>K</kbd> to search directory paths across the curren
 
 Results can be incomplete while Sambee scans folders. During a scan, the status shows directories found or directories checked. An interrupted scan keeps committed progress for its next attempt. If a folder is missing from search, browse to it directly.
 
+Status messages identify the connection. **Not all directories could be indexed** means some folders were skipped; available results remain usable. When a message has additional details, it appears as a link that you can click or tap. The status dialog lists affected locations and reasons, or specific request-error details. These links are outside keyboard navigation so focus stays in the quick bar.
+
+Directory details are a limited sample from the current running source, not a full error history. They can be unavailable after a restart until another scan collects them. Check the listed folder permissions or names when applicable. Some locations are deliberately excluded for safe traversal and do not require a repair.
+
 If directory search is temporarily unavailable, the quick bar keeps recent history and results already shown for the same search. It checks for recovery while open. A paused status does not mean that a scan is still running. Restore source access if the message reports a connection problem; direct browsing can remain available while search recovers.
 
 Directory indexes are reused after a restart. Results can remain unverified while background checks run. Missing removable media keeps its saved index; insert or mount the volume again to resume search. SMB search includes ordinary folders inside the configured share and folder, including server-mounted storage. Local search does not cross into other mounts. Redirects and reparse points are excluded.
diff --git a/website/content/docs/2.0/user-guide/use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/index.md b/website/content/docs/2.0/user-guide/use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/index.md
index 9a049958..2c82c0e4 100644
--- a/website/content/docs/2.0/user-guide/use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/index.md
+++ b/website/content/docs/2.0/user-guide/use-local-drives-and-desktop-apps/install-and-pair-the-companion-app/index.md
@@ -56,3 +56,5 @@ If a local drive reports a pairing error, open **Settings** > **Local Drives** f
 1. Run **Test Current Pairing**. If it still fails with a signature error after reloading, use **Pair This Browser** and approve the new code in Companion.
 
 If Sambee cannot check the pairing status, select **Retry**. Wait for a confirmed status before starting a new pairing. Companion pairing secrets do not expire on a 30-day timer. An unavailable Companion or a temporary failed check does not mean you need to re-pair.
+
+If settings show **Pairing required**, Companion could not authenticate this browser. Automatic settings checks pause to avoid repeated failed requests. Follow the pairing recovery steps above. Successful pairing restarts settings synchronization; **Retry** starts a new check without removing the stored pairing or settings.